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PREFACE 



The purpose of this publication is to 
enable programmers to compile, link-edit, 
and execute, or compile and load Full 
American National Standard COBOL Compiler 
and Library, Version 4, programs under 
control of the IBM Operating System. The 
COBOL language is described in the 
publication IBM O S Full American N ational 
Stan dard COBOL , Order No. GC28-6396, which 
is a corequisite to this publication. 

Programmers who are familiar with the 
operating system and wish to know how to 
run COBOL programs should read "Job Control 
Statements" and "Data Set Requirements" 
under "Job Control Procedures, " and 
"Output." These chapters provide 
information about the preparation of COBOL 
programs for processing by the operating 
system. 

Programmers who are unfamiliar with the 
concepts of OS should read "Introduction, " 
"Job Control Procedures, " "Checklist for 
Job control Procedures, " and "Using 
Cataloged Procedures" in addition to the 
sections listed above. 

The chapters "Program Checkout" and 
"Programming Techniques" are of special 
interest, since they contain information 
about debugging and efficient programming. 
Other chapters discuss optional features of 
the language and the operating system. 
Some chapters include introductory 
information about features of the operating 
system that are described in detail in 
other publications. 

The chief features available with this 
compiler are Optimized Object Code, COBOL 
Teleprocessing, and Advanced Symbolic 
Debugging capabilities. With the 
Teleprocessing Feature, the user can write 
device-independent message-processing 
programs using COBOL language statements to 
send and receive messages over a 
communications network. The Optimized 
Object Code Feature allows for a 
considerable reduction in object-time code. 
Advanced Symbolic Debugging — 
incorporating symbolic dumping 
capabilities, a flow trace of a 
user-specified number of procedures, and 
the number of the source statement causing 
abnormal termination — can result in a 
marked saving of debugging time. 

Additional features of this compiler 
provide for a syntax-only compilation, 
significantly reducing compilation time; 
the sharing of reentrant COBOL object- time 



library subroutines by multiple 
regions/partitions; dynamic invocation and 
release of user subprograms; and 
manipulation of data to separate contiguous 
data into multiple logical subfields or to 
concatenate two or more subfields into a 
single field. 



The machine configuration required for 
system operations is described in the 
chapter "Machine Considerations." 

Wider and more detailed discussions of 
the operating system are given in the 
following publications: 

I BM OS Job Control Language Reference , 
Order No. GC28-670U 

IBM OS Job_ Con trol_Language Charts, 
Order No. GC28-6632 

IBM OS Sy stem Prog rammer 1 ^ Guide, Order 
No. GC28-6550 

IBM OS Linkage Edit or and Loader, Order 
No. GC28-6538 

IBM OS Supervisor _§ervices, Order 
No. GC28-6646 

I BM OS" Data Management Servic es , Order 
No. GC26-3746 

IBM OS Supervisor and Data M ana gement 
Macro In structions, Order No. GC28-66U7 

IBM OS Sort/Merge, Order No. GC28-6543 

IBM OS Sort/Merge Programmer* s 3uide, 
Order No. SC33-4007 

IBM OS Utilities , Order No. GC28-6586 

IBM OS Syst em Generation, Order 
No. GC28-6554 

IBM OS P rogrammer's Guide to Debug gi ng, 
Order No. GC28-6670 

IBM OS Storage Estimates, Order 
No. GC28-6551 

IBM OS_Messages and Codes, Order No. 
GC28-6631 



Diagnostic messages, together with their 
problem determination documentation can be 
found in the following publication: 



IBM OS Full Ameri can Na tional Standard 
COBOL, Ve rsi on ^ Me ssages , Order 
No. SC28-6457 



Information on installing the compiler 
and using it under the Time Sharing Option 
<TSO) of the IBM Operating System can be 
found in the following Program Product 
publications : 



The COBOL teleprocessing user must write 
a message control program (MCP) to handle 
messages transmitted between remote 
stations and the central computer before 
they can be processed by a COBOL program. 
General telecommunications access method 
(TCAM) information, as well as specific 
guidelines for creating an MCP, can be 
found in the following publications: 



I BM OS Full American National Stan dard 
C OBOL Compiler and Library, Ve rsion H t 
In stallation Reference Materia l, Order 
No. SC28-6458 



IB M OS Telecommunications Access M ethod 
(TCAM) Concepts and Facilities , Order 
No. GC30-2022. 



IBM OS (TS O) ; COBOL Prompter 
In stallation R e ference Materia l, Order 
No. SC28-6434 



IBM OS Telecommunications Access Method 

!TCAM) Programmer 1 ^ Guide an d Re fer ence 

Material, Order No. GC30-2024. 
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INTRODUCTION 



An American National Standard COBOL 
program can be processed by the IBM 
Operating System. The operating system 
consists of a number of processing programs 
and a control program. 

The processing programs include the 
COBOL compiler, service programs, and any 
user-written programs. 

The control program supervises the 
execution or loading of the processing 
programs; controls the location, storage, 
and retrieval of data; and schedules jobs 
for continuous processing. 

A request to the operating system for 
facilities and scheduling of program 
execution is called a job . For example, a 
job could consist of compiling a program by 
utilizing the COBOL compiler. A job 
consists of one or more job s teps , each of 
which specifies execution of a program. 
The programmer can make requests to the 
operating system by using job control 
statements. 



Each job is headed by a JOB statement 
that identifies the job. Each job step is 
headed by an EXEC statement that describes 
the job step and calls for execution. 
Included in each job step are data 
definition (DD) statements, which describe 
data sets and request allocation of 
input/output devices. 



The data processed by execution of any 
processing program must be in the form of a 
d ata set. A data set is a named, organized 
collection of one or more records that are 
logically related. Information in a data 
set may or may not be restricted to a 
specific type, purpose, or storage medium. 
A data set may be, for example, a source 
program, a library of subroutines, or a 
group of data records that is to be 
processed by a COBOL program. 



data set name, in the system c atalo g of 
data sets. The catalog itself is a data 
set residing on one or more mass storage 
devices. It is organized into indexes that 
relate each data set name to its location — 
the volume in which it resides and its 
position within the volume. Only the data 



1am 



DISP parameter need be 



specified to identify a cataloged data set 
to the system. 

The catalog is originally created by a 
utility program. Once the catalog exists, 
any data set residing on either a mass 
storage device or a magnetic tape volume 
can be cataloged automatically by use of a 
catalog subparameter in a DD statement that 
refers to the data set. 



Several input/output devices grouped 
together and given a single name when the 
system is generated constitute a device 
cla ss. Each device class can be referred 
to by a collective name. For example, one 
device class called SYSDA could consist of 
all the mass storage devices in the 
installation; another called SYSSQ could 
consist of all the mass storage devices and 
tape devices. 



EXECUTI NG A COBOL PROGRAM 

Four basic operations are performed to 
execute a COBOL program: 

• Compilation 

• Linkage editing 

• Loading 

• Execution 

COMF1 LATION 



A data set resides in one or more 
volumes. A volume is a unit of external 
storage that is accessible to an 
input/output device. For example, a volume 
may be a reel of tape or it may be a mass 
storage device. 

To facilitate retrieval of a data set, 
the serial number of the volume upon which 
it resides can be entered, along with the 



Compilation is the process of 
translating a COBOL source program into a 
series of instructions comprehensible to 
the computer, i.e., machine language. In 
operating system terminology, the input 
(source program) to the compiler is called 
the source_module. The output (compiled 
source program) from the compiler is called 
the obj^ct_module. 
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LINKAGE EDITING 



OPERATING SYSTEM ENVIRONMENTS 



The linkage editor is a service program 
that prepares object modules for execution. 
It can also be used to combine two or more 
separately compiled object modules into a 
format suitable for execution as a single 
program. The executable output of the 
linkage editor is called a loa d module, 
which must always be stored as a member of 
a partitioned data set. 



The IBM Operating System offers two 
control programs. These are 
Multiprogramming with a Fixed Number of 
Tasks (MFT) and Multiprogramming with a 
Variable Number of Tasks (MVT). 



In addition to processing object 
modules, the linkage editor can combine 
previously edited load modules, with or 
without one or more object modules, to form 
one load module. 



During the process of linkage editing, 
external references between different 
modules are resolved. 



MULTIPROGRAMMING WITH A FIXED NUMBER OF 
TASKS 



The multiprogramming with a fixed number 
of tasks (MFT) control program divides 
storage into a number of discrete areas 
called partitions. Job steps are directed 
to these partitions using a priority 
scheduling system; that is, jobs are not 
executed as encountered in the job stream 
but according to a priority code. The MFT 
control program provides for: 



• Priority scheduling of jobs using the 
class code 



LOADING 



The Loader is a service program that 
processes COBOL object and load modules, 
resolves any references to subprograms, and 
executes the loaded module. All these 
functions are performed in one step. The 
Loader cannot produce load modules for a 
program library. 



For detailed information on the Loader, 
see the publication IB M OS Linkag e Edi tor 
and Loader , where a discussion of invoking 
the Loader can be found in "Using the 
Cataloged Procedures." 



Concurrent scheduling and execution of 
up to 15 separately protected jobs 



• Reading one or more input streams 



For further information about the 
various optional features of the MFT 
control program, see the publication I BM OS 
§t2£^5L§_?§ t i ma t e s . 



MULTIPROGRAMMING WITH A VARIABLE NUMBER OF 
TASKS 



EXECUTION 



Actual execution is under supervision of 
the control program, which obtains a load 
module from a library, loads it into main 
storage, and initiates execution of the 
machine language instructions contained in 
the load module. 



The multiprogramming with a variable 
number of tasks (MVT) control program 
divides storage into areas called regions. 
Like MFT, the MVT control program uses a 
priority scheduling system and provides for 
concurrent execution of up to 15 jobs. In 
addition, the MVT control program provides 
for assignment of storage regions on a 
variable basis according to a region code. 



JOB CONTROL PROCEDURES 



Communication between the COBOL 
programmer and the job scheduler is 
effected through nine job control 
statements (hereinafter called control 
statements) : 



1. Job Statement 

2. Execute Statement 

3. Data Definition Statement 

4. PROC Statement 

5. PEND Statement 

6. Command Statement 

7. Delimiter Statement 

8. Null Statement 

9. Comment Statement 



Parameters coded in these control 
statements aid the job scheduler in 
regulating the execution of jobs and job 
steps, retrieving and disposing of data, 
allocating input/output resources, and 
communicating with the operator. 

The job stateme nt (hereinafter called 
the JOB statement) marks the beginning of a 
job and, when jobs are stacked in the input 
stream, marks the end of the control 
statements for the preceding job. It may 
contain accounting information for use by 
an installation* s accounting routines, give 
conditions for early termination of the 
job, and regulate the display of job 
scheduler messages. With priority 
schedulers, additional parameters are used 
to assign job priority, to request a 
specific class for job scheduler messages, 
to specify the amount of main storage to be 
allocated to the job, and to hold a job for 
later execution. 

The execute st a tement (or EXEC 
statement) marks the beginning of a job 
step and identifies the program to be 
executed or the cataloged procedure to be 
used. It may also provide job step 
accounting information, give conditions for 
bypassing the job step, and pass control 
information to a processing program. With 
priority schedulers, additional parameters 
assign a time limit for the execution of 
the job step and specify the amount of main 
storage to be allocated. 



The data definition statement (or DD 
statement) describes a data set and 
requests the allocation of input/output 
resources. The DD statement parameters 
identify the data set, give volume and unit 
information and disposition, and describe 
the labels and physical attributes of the 
data set. 



The PROC statement appears as the first 
control statement in a cataloged procedure 
or an in-stream procedure and is used to 
assign default values to symbolic 
parameters defined in the procedure. 



The PEND s t atement appears as the last 
control statement in an in-stream procedure 
and marks the end of the in-stream 
procedure. For further information about 
in-stream procedures, refer to the topic 
"Testing a Procedure as an In-Stream 
Procedure" in the chapter "Using the 
Cataloged Procedures. " 

The command statement is used by the 
operator to enter commands through the 
input stream. Commands can activate or 
deactivate system input and output units, 
request printouts and displays, and perform 
a number of other operator functions. 

The delimiter statement and the null 
statement are markers in an input stream. 
The delimiter statement is used, when data 
is included in the input stream, to 
separate the data from subsequent control 
statements. The null statement can be used 
to mark the end of the control statements 
for certain jobs. 

The comment statement can be inserted 
before or after any control statement and 
can contain any information deemed helpful 
by the person who codes the control 
statements. Comments can be coded in 
columns 4 through 80. The comment cannot 
be continued onto another statement. If 
the comment statement appears on a system 
output listing, it can be identified by the 
appearance of asterisks in columns 1 
through 3. 

The sequence of control statements 
required to specify a job is called a job 



control pr ocedure . 



For example, the job control procedure 
shown in Figure 1 could be placed in the 
input stream to compile a COBOL source 
module. 
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//J0B1 


JOB 


//STEP1 


EXEC 


//SYSUT1 


DD 


//SYSUT2 


DD 


//SYSUT3 


DD 


//SYSUT4 


DD 


//SYSPRINT 


DD 


//SYSPUNCH 


DD 


//SYSIN 


DD 



/* 



(source deck) 



PGM=IKFCBL00 , PARM=DECK 

DSNAME=6SUT1,UNIT=SYSDA,SPACE= (TRK, (40) ) 
DSNAME=g&UT2,UNIT=SYSSQ,SPACE=(TRK, (40)) 
DSNAME=gSUT3,UNIT=SYSSQ,SPACE=(TRK, (40)) 
DSNAME=SgUT4,UNIT=SYSSQ,SPACE=(TRK, (40) ) 
SYSOUT=A 
SYSOUT=B 
* 



Figure 1. Job Control Procedure 



In the illustration, JOB1 is the name of 
the job. The JOB statement indicates the 
beginning of a job. 



STEP1 is the name of the single job step 
in the job. The EXEC statement specifies 
that the IBM OS Full American National 
Standard COBOL Compiler (IKFCBL00) is to 
execute the job. The statement also 
specifies that a card deck of the object 
module is to be produced (PARM=DECK) . 

Note: Under MVT a REGION parameter is also 
reguired. 

The SYSUTl, SYSUT2, SYSUT3, SYSUT4, and 
SYSUT5 (if the SYMDMP option is specified 
in the PARM parameter of the EXEC card) DD 
statements define utility data sets used by 
the compiler to process the source module. 
The names of the data sets defined by 
SYSUTl, SYSUT2, SYSUT3, SYSUT4, and SYSUT5 
are &&UT1, &&UT2, S&UT3, &&UT4, and &6UT5, 
respectively. SYSUTl must be on a mass 
storage device <UNIT=SYSDA) . The system 
will allocate 40 tracks of space to SYSUTl 
[SPACE=(TRK, (40) )]. The other three 
utility data sets are assigned either to 
any available tape, in which case the SPACE 
parameter is ignored, or to a mass storage 
unit (UNIT=SYSSQ). 

The SYSPRINT DD statement defines the 
data set that is to be printed. SYSOUT=A 
is the standard designation for data sets 
whose destination is the system output 
device, usually indicating that the data 
set is to be listed on a printer. 

The SYSPUNCH DD statement defines the 
data set that is to be punched. SYS0UT=B 
designates a card punch. 

The SYSIN DD statement defines the data 
set (in this case, the source module) that 
is to be used as input to the job step. 
The asterisk (*) indicates that the input 
data set follows in the input stream. 



The delimiter (/*) statement separates 
data from subseguent control statements in 
the input stream. 

Output from this job step includes any 
diagnostic messages associated with the 
compilation. They are printed in the data 
set specified by SYSPRINT. 

Note : SYSDA, SYSQ, A, and B are 
IBM-specified device class names. If they 
are to be used, they must be incorporated 
at system generation time. If SYSOUT=B is 
to be used, the unit name SYSCP must be 
specified at system generation. 

To avoid rewriting these statements, and 
the possibility of error, the programmer 
may place frequently used procedures on a 
system library called the procedure 
library. A procedure contained in the 
procedure library is called a cat.alog.ed 
pro ce dure . A cataloged procedure can be 
called for execution by placing in the 
input stream a simple procedure that may 
require only the JOB and EXEC statements. 

If slightly modified, the procedure in 
the previous example can be cataloged, 
i.e., placed in the procedure library. For 
example, if it were cataloged and given the 
name CATPROC, it could be called for 
execution by placing the statements shown 
in Figure 2 in the input stream. 



| //JOB2 JOB 
| //STEPA EXEC 
J//STEP1.SYSIN DD 
J (source deck) 



PROC=CATPKOC 

* 



Figure 2. Catalog Procedure 



In Figure 2, JOB2 is the name of the job. 
STEPA is the name of the single job step. 



i» 



The EXEC statement calls the cataloged 
procedure containing STEP1 to execute the 
job Step (PROC=CATPROC) . 

A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stre am procedure. 
An in-stream procedure can be executed any 
number of times during a job. For further 
information about in-stream procedures, 
refer to the topic "Testing a Procedure as 
an In-Stream Procedure" in "Using the 
Cataloged Procedures. " 

"User File Processing" and "Appendix I: 
Checklist for Job Control Procedures" 
explain, with numerous examples, the 
preparation of job control procedures. 
"Data Set Requirements" describes required 
and optional data sets for compilation, 
linkage editing, and execution time job 
steps. The chapter "Using Cataloged 
Procedures" provides information about 
using and modifying cataloged procedures. 

The section "Control Statements, " below, 
shows the format and use of the parameters 
and subparameters that can be specified for 
each job control statement. Some 
parameters of the statements are described 
only briefly. For further information, see 
the publication IBM OS J ob Contro l Language 
R efe rence. The syntactic format 
descriptions in this chapter can be used as 
a reference for the exact format and for 
the use of each parameter. 



CONTROL STATEMENTS 



The COBOL programmer uses the control 
statements shown in Table 1 to compile, 
linkage edit, and execute programs. 



Table 1. Control Statements 



r t- 

| Statement! 



Function 



|. 4 .J 



JOB | Indicates the beginning of a 
j new job and describes that 
1 job. 


T 

EXEC | Indicates a job step and 

j describes that job step; 
j indicates the load module or 
j cataloged procedure to be 
| executed. 


~ T ~ 
DD | Describes data sets, and 

| controls device and volume 
1 assignment. 


T 

delimiter | Separates data sets in the 
| input stream from control 
| statements; it must follow 
j each data set that appears in 
| the input stream, e.g., after 
j a COBOL source module punched 
j deck. 
4- - - 


T 

comment | Contains miscellaneous remarks 
| and notes written by the 
j programmer; it may appear 
| anywhere in the job stream 
| after the JOB statement. 



L ± J 



The master scheduler is a set of 
routines that accepts operator commands and 
acts as the operator' s agent within the 
system. It relays system messages to the 
operator, performs system functions at his 
request, and responds to his inquiries 
regarding the status of a job or of the 
system. The master scheduler also relays 
all communication between a processing 
program and the operator. 



JOB MANAGEMENT 



Control statements are processed by a 
group of operating system routines known 
collectively as job management. These job 
management routines interpret control 
statements and commands, control the flow 
of jobs, and issue messages to both the 
operator and the programmer. Job 
management comprises two major components: 
a job scheduler and a master scheduler. 

The job scheduler is a set of routines 
that reads input streams, analyzes control 
statements, allocates input/output 
resources, issues diagnostic messages to 
the programmer, and schedules job flow 
through the system. 



Pr iority schedulers process complete 
jobs according to their relative priority, 
and available system resources. 



PREPARING CONTROL STATEMENTS 



Except for the comment statement, 
control statements are identified by the 
initial characters // or /* in card columns 
1 and 2. The comment statement is 
identified by the initial characters //* in 
columns 1 through 3. Control statements 
may contain four fields: name, operation, 
operand, and comment, as shown in Figure 3. 
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Statement 



Columns 



Fields 



_ T _ T — T 

1|2|3 | 4 



+—+- + - 

/!/ 

/|* 
/|/ 
/|/ 



Job 

Execute 

Data Definition 

Procedure 

Command 

Delimiter 

Null 

Comment 

Pend 



name JOB operand 1 comments 1 
name 1 EXEC operand comments 1 
name 1 DD operand comments 1 



PROC 



operand 



operation ( command ) 

comments 1 

* comments 
name 1 PEND 



comments 1 
operand 



comments 1 



| 1 0ptional. 
l 



Figure 3. General Format of Control Statements 



Name Field 



Operand_Field 



The name contains from one through eight 
alphanumeric characters, the first of which 
must be alphabetic. The name begins in 
card column 3. It is followed by one or 
more blanks. The name is used, as follows: 



• To identify the control statement to 
the operating system 



To enable other control statements in 
the job to refer to information 
contained in the named statement 



• To relate DD statements to files named 
in a COBOL source program 



Opera tion Field 



The operation field is preceded and 
followed by one or more blanks. It may 
contain one of the following operation 
codes : 

JOB 

EXEC 

DD 

PROC 

PEND 



If the statement is a delimiter statement, 
there is no operation field and comments 
may start after one blank. 



The operand field is preceded and 
followed by one or more blanks and may 
continue through column 71 and onto one or 
more continuation cards. It contains the 
parameters or subparameters that give 
required and optional information to the 
operating system. Parameters and 
subparameters are separated by commas. A 
blank in the operand field causes the 
system to treat the remaining data on the 
card as a comment. There are two types of 
parameters: positional and keyword 
(Figures 4, 5, and 7). 

Positional Pa rameters: Positional 
parameters are the first parameters in the 
operand field, and they must appear in the 
specified sequence. If a positional 
parameter is omitted and other positional 
parameters follow, the omission must be 
indicated by a comma. If other positional 
parameters do not follow, no comma is 
needed. 

Keyword Parameters : A keyword parameter 
may be placed anywhere in the operand field 
following the positional parameters. A 
keyword parameter consists of a keyword, 
followed by an equal sign, followed by a 
single value or a list of subparameters. 
If there is a subparameter list, it must be 
enclosed in parentheses or single quotation 
marks; the subparameters in the list must 
be separated by commas. Keyword parameters 
may appear in any sequence. 

Subparameters are either positional or 
keyword. Positional and keyword 
subparameters for job control statements 
are shown in Figures 4, 5, and 7. 
Positional subparameters appear first in 
the parameter and must be in the specified 
sequence. If a positional subparameter is 



on 



omitted and other positional subparameters 
follow, a comma must indicate the omission. 



Comments Field 



1 through 71 of cards or card images. If 
the total length of a statement exceeds 71 
columns, or if a parameter is to be placed 
on separate cards, the operating system 
continuation conventions must be used. To 
continue an operand field: 



Optional comments must be separated from 
the last parameter (or the /* in a 
delimiter statement) by one or more blanks 
and may appear in the remaining columns up 
to and including column 71. An optional 
comment may be continued onto one or more 
continuation cards. Comments can contain 
blanks. 

Note : Comments in the optional comments 
field follow different procedures from 
those on the comment statement. 



CONVENTIONS FOR CHARACTER DELIMITERS 



Commas, parentheses, and blanks are 
interpreted as character delimiters. If 
they are not intended by the programmer to 
be used as delimiters, the fields in which 
they appear must be enclosed in single 
quotation marks, indicating that the 
enclosed information is to be treated as a 
single field. When an apostrophe (or a 
single quotation mark, since the same 
character is used for either) is to be 
contained within such a field, it must be 
shown as two consecutive single quo tation 
marks (5-8 punch), not as a double 
quotation mark (7-8 punch) . For example, 

Wm. O'Connor 

should be shown as 

' Wm. 0" * Connor' 



This convention applies to three fields: 
programmer* s name in the JOB statement, 
information in the PARM parameter of the 
EXEC statement, and accounting information 
in the JOB and EXEC statements. 



1. Interrupt the field at the end of a 
complete parameter or subparameter, 
including the comma that follows it, 
at or before column 71. 



2. Include comments by following the 
interrupted field with at least one 
blank. 



3. Optionally, code any nonblank 
character in column 72. If a 
character is not coded in column 72, 
the job scheduler treats the next 
statement as a continuation statement 
as long as the conventions outlined in 
items 4 and 5 are observed. 

4. Code the identifying characters // in 
columns 1 and 2 of the following card 
or card image. 

5. Continue the interrupted operand 
beginning in any column from 4 through 
16. 



Comments other than those on a comment 
statement can be continued onto additional 
cards after the operand has been completed. 
To continue a comments field: 

1. Interrupt the comment at a convenient 
place. 

2. Code a nonblank character in column 
72. 

3. Code the identifying characters // in 
columns 1 and 2 of the following card 
or card image. 

4. Continue the comments field beginning 
in any column after column 3. 



RULES FOR CONTINUING CONTROL STATEMENTS 



Except for the comment statement, 
control statements are contained in columns 



Any control statements in the input 
stream that the job scheduler considers to 
contain only continued comments will print 
on a system output listing with a //* in 
columns 1 through 3. Comments written on a 
comment statement cannot be continued. 
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NOTATION FOR DESCRIBING JOB CONTROL 
STATEMENTS 



The notation used in this publication to 
define the syntax of job control statements 
is as follows: 



1. The set of symbols below define 

control statements, but they are never 
written in an actual statement. 



Stacked items, enclosed in either 
brackets or braces, represent 
alternative items. No more than one 
of the stacked items can be written by 
the programmer. 

Upper-case letters and words, numbers, 
and the set of symbols listed below 
are written in an actual control 
statement exactly as shown in the 
statement definition. (Any exceptions 
to this rule are noted in the 
definition of a control statement. ) 



N ame Symbol 
hyphen 



"or" symbol | 
braces { } 



brackets [ ] 



ellipsis 



superscript 



Purpose 
Joins lower-case 
letters, words, and 
symbols to form a 
single variable 

Indicates alternatives 

Indicate that the 
enclosed is a group of 
related items, only 
one of which is 
required 

Indicate that the 
enclosed are optional 
items. Brackets are 
also used with 
alternatives to 
indicate that a 
default is assumed if 
no alternative is 
listed 

Indicates that the 
preceding item or 
group of items can be 
repeated 

Indicates a footnote 
reference 



Name 

single quotation mark 

asterisk 

comma 

equal sign 

parentheses 

period 

slash 



Symbol 

* 
i 

( ) 

/ 



4. An underscore indicates a default 

option. If an underscored alternative 
is selected, it need not be written in 
the actual statement. 

Note: Many of these defaults can be 
changed at system generation time. 



5. Lower-case letters, words, and symbols 
appearing in a control statement 
definition represent variables for 
which specific information is 
substituted in the actual statement. 



Blanks are used in Figures 4, 5, 6, 
and 7 to improve the readability of 
control statement definitions. In 
actual statements, blanks would be 
interpreted as delimiters. 
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Name 



t-- 



j Operation! 
-4 +- 



Operand 



//jobname 



JOB 



Positi onal Parameters 
[([account-number] [, accounting-information] ) x 2 3 ] 
[, programmer -name] H 5 

Keyword Parameters 

[MSGLEVEL=(x,y)] 6 

[TIME= (minutes, seconds) ] 

[CLASS=jobclass] 

[COND=( (code, operator) [, (code, operator) ] . . . 7 ) 8 ] 

[PRTY=job priority] 

[MSGCLASS=classname] 

[REGION= ( nnnnnxK [ , nnnnnyK] ) ] 

[ROLL=(x,y)] 

[TYPRUN=HOLD] 

[RD=request] 

[RESTART=(<> stepname i [,checkid]) ] 

stepname. procstepname j 



*-If the information specified (account-number and/or accounting-information) contains 

blanks, parentheses, or equal signs, the information must be delimited by single 

quotation marks instead of parentheses. 
2 If only account-number is specified, the delimiting parentheses may be omitted. 
3 The maximum number of characters allowed between the delimiting quotation marks is 

142. 
**If programmer-name contains any special characters other than the period, it must be 

enclosed within single quotation marks. 
5 The maximum number of characters allowed for programmer-name is 20. 
6 x = 0, 1, or 2 is the JCL message. 

y = or 1 is the allocation message level. 

Note that the value 1 may be used in place of (1,1). 
7 The maximum number of repetitions allowed is 7. 
8 If only one test is specified, the outer pair of parentheses may be omitted. 



Figure 4. JOB Statement 



JOB STATEMENT 



The JOB statement is the first statement 
in the sequence of control statements that 
describe a job. The JOB statement can 
contain the following information: 

Is Name of the job. 

2. Accounting information relative to the 
job. 

3. Programmer' s name. 

4. Indication of whether or not the job 
control statements are to be printed 
on the system output listing. 

5. Conditions for terminating the 
execution of the job. 



6. For priority scheduling systems: job 
priority assignment, job scheduler 
message class, and for the MVT 
environment, main storage region size. 



Figure 4 is a general format of the JOB 
statement. 



Identifying the Job (jobnam e) 



The jobname identifies the job to the 
job scheduler. It must satisfy the 
positional, length, and content 
requirements for a name field. No two jobs 
being handled by a priority scheduler 
should have the same jobname. 
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JOB PARAMETERS 



Identifying the Programmer 



Supp l ying Job A ccou nting Informat ion 



For job accounting purposes, the JOB 
statement can be used to supply information 
to an installation's accounting procedures = 
To supply job accounting information, code 
the positional parameter first in the 
operand field. 



r 1 

| (acct#, additional accounting information)! 

l J 



Replace the term "acct#" with the account 
number to which the job is charged; replace 
the term "additional accounting 
information" with other items required by 
an installation' s accounting routines. As 
a system generation option with sequential 
schedulers, the account number can be 
established as a required subparameter. 
With priority schedulers, the requirement 
can be established with a cataloged 
procedure for the input reader. Otherwise, 
the account number is considered optional. 



Notes : 



Subparameters of additional accounting 
information must be separated by 
commas. 

The number of characters in the account 
number and additional accounting 
information must not exceed a total of 
142. 



The person responsible for a job codes 
his name or identification in the JOB 
statement, following the job accounting 
information. This positional parameter is 
also passed to an installation* s routines. 
As a system generation option with 
sequential schedulers, the programmer's 
name can be established as a required 
parameter. With priority schedulers, the 
requirement can be established with a 
cataloged procedure for the input reader. 
Otherwise, this parameter is considered 
optional. 



Notes : 



The number of characters in the name 
cannot exceed 20. 

If the name contains special characters 
other than periods, it must be enclosed 
in apostrophes. If the special 
characters include apostrophes, each 
must be shown as two consecutive 
apostrophes, e.g., ' T. O' ' NEILL' . 



• If the job accounting information is 
not coded, the programmer must indicate 
its absence by coding a comma preceding 
the programmer-name. 



If neither job accounting information 
nor programmer-name is present, the 
programmer need not code commas to 
indicate their absence. 



Reference: 



• If the list contains only an account 
number, the programmer need not code 
the parentheses. 

• If the list does not contain an account 
number, the programmer must indicate 
its absence by coding a comma preceding 
the additional accounting information. 



To write a routine that processes the 
programmer's name, see the section 
"Adding an Accounting Routine to the 
Control Program" of the publication IBM 
OS System Programmer's Guide. 



• If the account number or any 

subparameter of additional accounting Displaying All Control Statements , 

information contains any special Allocation, and Termination Mess ag es 

character (except hyphens), the (MSGLEVEL) 

programmer must enclose the number or 

subparameter in apostrophes (5-8 

punch). The apostrophes are not passed The MSGLEVEL parameter indicates whether 

as part of the information. or not the programmer wants control 

statements and/or allocation and 

Reference: termination messages to appear in his 

output listing. To receive this output, 

• To write an accounting routine that code the keyword parameter in the operand 
processes job accounting information, field of the JOB statement. 

see the section "Adding an Accounting 

Routine to the Control Program" of the r 

publication IBM OS Sy stem Programmer's j 

Guide. l 



MSGLEVEL=(x,y) 
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The letter "x" represents a job control 
language message code and can be assigned 
the value 0, 1, or 2. When x = is 
specified, only the JOB statement, 
incorrect control statements, and 
associated diagnostic messages are 
displayed. When x = 1 is specified, input 
statements, cataloged procedure statements, 
and symbolic substitution of parameters are 
displayed. When x = 2 is specified, only 
input statements are displayed. 



The letter "y" represents an allocation 
message code and can be assigned the value 
or 1. When y = is specified, no 
allocation, termination, or recovery 
messages are displayed, unless an ABEND 
occurs during problem program execution. 
If an ABEND occurs, termination messages 
are displayed. When y = 1 is specified, 
all allocation, termination, and recovery 
messages are displayed. 

Notes : 



See the COND parameter on the EXEC 
statement for a discussion of the operator 
values and the codes issued by the compiler 
and linkage editor at the end of a job 
step. 



Note: 



The subparameters EVEN and ONL5f cannot 
be specified as part of the COND 
parameter on the JOB statement. 



Requesti ng Restart for a Job (RD) 



The restart facilities are used in order 
to minimize the time lost in reprocessing a 
job that abnormally terminates. These 
facilities permit execution of jobs that 
abnormally terminate to be automatically 
restarted. 



If the value 1 is selected for both 
codes, the value may be specified once 
without the parentheses; i.e., 
MSGLEVEL=1 is the same as 
MSGLEVEL=(1,1). 

The default values are taken from the 
reader procedure. 

If an error occurs on a control 
statement that is continued onto one or 
more cards, only one of the 
continuation cards is printed with the 
diagnostic messages. 



S pec ifyi ng Condit ions for Job Ter mina tion 
(COND) 



To eliminate unnecessary use of 
computing time, the programmer might want 
to base the continuation of a job on the 
successful completion of one or more of its 
job steps. At the completion of each job 
step, the processing program passes a 
number to the job scheduler as a return 
code* The COND parameter provides the 
means to test each return code as many as 
eight times. If any one of the tests is 
satisfied, subsequent steps are bypassed 
and the job is terminated. 

To specify conditions for job 
termination, code the keyword parameter in 
the operand field of the JOB statement. 



r 1 

| C0ND=( (code, operator) , . . , (code, operator) ) | 

l J 



Execution of a job can be automatically 
restarted at the beginning of the job step 
that abnormally terminated (step restart) 
or within the step (checkpoint restart). 
In order for checkpoint restart to occur, 
the CHKPT macro instruction must have been 
executed in the processing program prior to 
abnormal termination. The CHKPT macro 
instruction is activated by the COBOL 
source language RERUN clause. The RD 
parameter specifies that step restart can 
occur or that the action of the CHKPT macro 
instruction is to be suppressed. 

To request that step restart be 
permitted or to request that the action of 
the RERUN clause be suppressed, code the 
keyword parameter in the operand field of 
the JOB statement. 



RD=request 



Replace the word "request" with: 

R — to permit automatic step 
restart 

NC — to suppress the action of the 

CHKPT macro instruction and not 
to permit automatic restart 

NR — to request that the CHKPT macro 
instruction be allowed to 
establish a checkpoint, but not 
to permit automatic restart 

RNC — to permit step restart and to 
suppress the action of the 
CHKPT macro instruction 
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Each of these requests is described in 
greater detail in the following paragraphs. 



RD=R : If the processing programs used by 
the job do not include any CHKPT macro 
instructions, RD=R allows execution to be 
resumed at the beginning of the step that 
causes abnormal termination. If any of the 
programs do include one or more CHKPT macro 
instructions, step restart can occur if a 
step abnormally terminates before execution 
of a CHKPT macro instruction; thereafter, 
checkpoint restart can occur. 



RD=NC o r RD=RNC : RD=NC or RD=RNC should be 
specified to suppress the action of all 
CHKPT macro instructions included in the 
programs. When RD=NC is specified, neither 
step restart nor checkpoint restart can 
occur. When RD=RNC is specified, step 
restart can occur. 

RD=NR : RD=NR permits a CHKPT macro 
instruction to establish a checkpoint, but 
does not permit automatic restart. 
Instead, at a later time, the job can be 
resubmitted and execution can begin at a 
specific checkpoint. (Resubmitting a job 
for restart is discussed later. ) 

Before automatic step restart occurs, 
all data sets in the restart step with a 
status of OLD or MOD, and all data sets 
being passed to steps following the restart 
step, are kept. All data sets in the 
restart step with a status of NEW are 
deleted. Before automatic checkpoint 
restart occurs, all data sets currently in 
use by the job are kept. 

If the RD parameter is omitted and no 
checkpoints are taken, automatic restart 
cannot occur. If the RD parameter is 
omitted but one or more checkpoints are 
taken, automatic checkpoint restart can 
occur. 

Notes : 



Resubmitting a Job for Resta rt (REST ART ) 



The restart facilities can be used if 
the job is abnormally terminated and the 
programmer wants to resubmit the job for 
execution. These facilities reduce the 
time required to execute the job since 
execution of the job is resumed, not 
repeated. 



Execution of a resubmitted job can be 
restarted at the beginning of a step (step 
restart) or within a step (checkpoint 
restart). In order for checkpoint restart 
to occur, a program must previously have 
had a checkpoint record written. The 
RESTART parameter specifies where execution 
is to be restarted. 



If execution is to be restarted at a 
particular job step, code the keyword 
parameter in the operand field of the JOB 
statement before resubmitting the job. 



RESTART=stepname 



Replace the word "stepname" with the name 
of the step at which execution is to be 
restarted. Replace stepname with an 
asterisk (*) if execution is to be 
restarted at the first job step. 

If execution is to be restarted at a 
particular checkpoint within a particular 
job step, code the keyword parameter in the 
operand field of the JOB statement before 
resubmitting the job. 



RESTART= ( stepname, checkid ) 



When using a system with MVT or MFT, 
restart can occur only if MSGLEVEL=1 is 
coded on the JOB statement. 

If step restart is requested, each step 
must be assigned a unique step name. 

If no RERUN clause is specified in the 
user's program, no checkpoints are 
written regardless of the disposition 
of the RD parameter. 



Reference: 



For detailed information on the 
checkpoint/restart facilities, see the 
publication IBM O S Su pervisor Services . 



Replace the word stepname with the name of 
the step in which execution is to be 
restarted. Replace the term "checkid" with 
the 1- to 16-character name that identifies 
the checkpoint within the step. 

If execution is to be restarted at a 
checkpoint, the resubmitted job must 
include an additional DD statement. This 
DD statement defines the checkpoint data 
set and has the ddname SYSCHK. Do not 
include a SYSCHK DD statement if step 
restart is to be performed. 

If the RESTART parameter is not 
specified on the JOB statement of the 
resubmitted job, execution is repeated. 
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Notes 



If execution is to be restarted at or 
within a cataloged procedure step, give 
both the name of the step that invokes 
the procedure and the procedure step 
name, as below. 



RESTART=stepname. procstepname 



• If step restart is performed, 
generation data sets that were created 
and cataloged in steps preceding the 
restarted step must not be referred to 
in the restart step or in steps 
following the restart step by means of 
the same relative generation numbers 
that were used to create them. For 
example, a generation data set assigned 
a generation number of +1, would be 
referred to as in the restart step or 
steps following the restart step. 

• Backward references cannot be made to 
steps that precede the restart step 
using the following keyword parameters: 
PGM, COND, SUBALLOC, and VOLUKE=REF, 
unless in the last case the referenced 
statement includes VOLUME=SER=(ser#) . 

R efe rence: 

• For detailed information on the 
checkpoint/restart facilities, see the 
publication IB M System/360 Op erating 
S ystem: Supervisor Services . 



• If the job requires use of the system 
for more than 24 hours (1439 minutes) 
specify TIME=1440. This number 
suppresses job timing. 

• If the time limit is given in minutes 
only, the parentheses need not be 
coded; e.g., TIME=5. 

• If the time limit is given in seconds, 
the comma must be coded to indicate the 
absence of minutes; e.g., TIME=(,4b). 

• If the TIME parameter is omitted, the 
default job time is assumed. 



Assigni ng a Job Class (CLASS) 



To assign a job class to a job, code the 
keyword parameter in the operand field of 
the JOB statement. 



CLASS=jobclass 



Replace the term "jobclass" with an 
alphabetic character A through 0. The use 
of this parameter and the meaning of the 
character A through are to be determined 
by each installation. 

If the CLASS parameter is omitted, or 
CLASS=A is coded, the default joo class of 
A is assigned to the job. 



Note : 



PRIORITY SCHEDULING JOB PARAMETERS 



Setti ng Job Time Lim it s (TIME) 



To assign a limit to the computing time 
used by a job, code the keyword parameter 
in the operand field. 



TIME= (minutes, seconds) 



Such an assignment is useful in a 
multiprogramming environment where more 
than one job has access to the computing 
system. The time is coded in minutes and 
seconds to represent the maximum time for 
execution of a job. 

Note s : 

• The number of minutes cannot exceed 
1439 and the number of seconds cannot 
exceed 59. If the job is not completed 
in this time it is terminated. 



• If an installation provides 

time-slicing facilities in a system 
with MFT, the CLASS parameter can be 
used to make the job part of the group 
of jobs to be time-sliced. 
Time-slicing permits the processing of 
tasks of equal priority so that each is 
executed for its specified period of 
time. At system generation, a group of 
contiguous partitions are selected to 
be used for time-slicing, and each 
partition is assigned at least one job 
class. If the job is to be 
time-sliced, specify a class that was 
assigned only to the partitions 
selected for time-slicing. 



Assigning Job Pr iority (PRTY) 



To assign a priority other than the 
default job priority (as established in the 
input reader procedure) , code the keyword 
parameter in the operand field of the JOB 
statement. 
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Reference: 



PRTY=nn 



Replace the letters "nn n with a decimal 
number from through 13 (the highest 
priority number is 13). 

If an installation provides time-slicing 
facilities in a system with MVT r the PRTY 
parameter can be used to make the job part 
of a group of jobs to be time-sliced. At 
system generation, the priority of the 
time-sliced group is selected. If the job 
priority number specified corresponds with 
the priority number selected for 
time-slicing, then the job will be 
time-sliced. 

If the PRTY parameter is omitted, the 
default job priority is assigned to the 
job. 



Note: Whenever possible, avoid using 
priority 13. This is used by the system to 
expedite processing of jobs in which 
certain errors were diagnosed. It is also 
intended for other special uses by future 
features of systems with priority 
schedulers. 



Requ e sting a Mess a ge Class (MSGCLAS S) 



With the quantity and diversity of data 
in the output stream, an installation may 
want to separate different types of output 
data into different classes. Each class is 
directed to an output writer associated 
with a specific output unit. The MSGCLASS 
parameter allows routing of all messages 
issued by the job scheduler to an output 
class other than the normal message 
class, A. 

To choose such a class, code the keyword 
parameter in the operand field of the JOB 
statement. 



For a more detailed discussion of 
output classes, see the publication IB M 
OS Operator's Reference , Order 
No. GC28-6691. 



Specifying Ma in Storage Requirements f or a 

Job_^REGION)_ 

(MVT only) 

For jobs that require an unusual amount 
of main storage, the JOB statement provides 
the REGION parameter. The REGION parameter 
specifies: 

• The maximum amount of main storage to 
be allocated to the job. This amount 
must include the size of those 
components required by the user' s 
program that are not resident in main 
storage. 

• The amount of main storage to be 
allocated to the job, and the storage 
hierarchy or hierarchies in which the 
space is to be allocated. This request 
should be made only if main storage 
hierarchy support has been specified 
during system generation. If an IBM 
2361 Core Storage, Model 1 or 2, is 
present in the system, processor 
storage is referred to as hierarchy 
and 2361 Core Storage is referred to as 
hierarchy 1. If 2361 Core Storage is 
not present but main storage hierarchy 
support was specified in system 
generation, a two-part region is 
established in processor storage when a 
region is defined to exist in two 
hierarchies. The two parts are not 
necessarily contiguous. 

To specify a region size, code the 
keyword parameter in the operand field of 
the JOB statement. 



REGION=(nnnnnxK[, nnnnnyK] ) 



MSGCLASS=x 



Replace the letter "x" with an alphabetic 
(A-Z) or numeric (0-9) character. An 
output writer, which is assigned to process 
this class, will transfer this data to a 
specific device. 

If the MSGCLASS parameter is omitted, or 
coded MSGCLASS=A, job scheduler messages 
are routed to the standard output class, A. 



To request the maximum amount of main 
storage required by the job, the term 
"nnnnnx" should be replaced with the number 
of 1024-byte areas allocated to the job, 
e.g., REGION=52K. This number can range 
from 1 to 5 digits but cannot exceed 16383. 

To request a region size and the 
hierarchy desired, the term nnnnnx is 
replaced with the number of contiguous 
1024-byte areas to be allocated to the job 
in hierarchy 0; the term "nnnnny" is 
replaced with the number of contiguous 
1024-byte areas to be allocated in 



hierarchy 1, e.g., REGION=(60K, 200K) . When 
only processor storage is used to include 
hierarchies and 1, the combined values of 
nnnnnx and nnnnny cannot exceed 16383. If 
2361 Core Storage is present, nnnnnx cannot 
exceed 16383 and, for a 2361 Model 1, 
nnnnny cannot exceed 1024, or 2048 for a 
2361 Model 2. Each value specified should 
be an even number. (If an odd number is 
specified, the system treats it as the next 
higher even number. ) 



If storage is requested only in 
hierarchy 1, a comma must be coded to 
indicate the absence of the first 
subparameter, e.g., REGION=(, 200K) . If 
storage is requested only in hierarchy 0, 
or if hierarchy support is not present, the 
parentheses need not be coded, e.g., 
REGION=70K. 



The job is then held until a RELEASE 
command is issued by the operator. This 
specification is particularly useful when 
one job must be run after another job has 
terminated. 



Specif ying Additio nal Sto r age (ROLL) 
(MVT only) 



To allocate additional main storage to a 
job step whose own region does not contain 
any more available space, code the keyword 
parameter in the operand field of the JOB 
statement. 



ROLL=(x, y) 



If the REGION parameter is omitted or if 
a region size smaller than the default 
region size is requested, it is assumed 
that the default value is that established 
by the input reader procedure. 



Notes : 



Region sizes for each job step can be 
coded by specifying the REGION 
parameter in the EXEC statement for 
each job step. However, if a REGION 
parameter is present in the JOB 
statement, it overrides REGION 
parameters in EXEC statements. 



If main storage hierarchy support is 
not included but regions are requested 
in both hierarchies, the region sizes 
are combined and an attempt is made to 
allocate a single region from processor 
storage. If a region is requested 
entirely from hierarchy 1, an attempt 
is made to allocate the region from 
processor storage. 



For information on storage requirements 
to be considered when specifying a 
region size, see the publication I BM OS 
Storage Estimates. 



Hold ing a Job for Later Execu tion 

To temporarily prevent a job from being 
selected for processing, code the keyword 
parameter in the operand field of the JOB 
statement. 



TYPRUN=HOLD 



In order to allocate this additional space 
to a job step, another job step may have to 
be rolled out, i.e., temporarily 
transferred to secondary storage. When x 
is replaced with YES, each of the 
programmer's job steps can be rolled out; 
when x is replaced with NO, the job steps 
cannot be rolled out. When y_ is replaced 
with YES, each job step can cause rollout; 
when y is replaced with NO, the job steps 
cannot cause rollout. If additional main 
storage is required for the job' s steps, 
YES must be specified for y. If this 
parameter is omitted, ROLL=( YES, NO) is 
assumed. ROLL parameters can also be coded 
in EXEC statements, but are superseded by a 
ROLL parameter coded in the JOB statement. 



EXEC STATEMENT 



The EXEC statement defines a job step 
and calls for its execution. It contains 
the following information: 

1. The name of a load module or the name 
of a cataloged procedure that contains 
the name of a load module that is to 
be executed. The load module can be 
the COBOL compiler, the linkage 
editor, the loader, or any COBOL 
program in load module form. 

2. Accounting information for this job 
step. 

3. Conditions for bypassing the execution 
of this job step. 

4. For priority scheduling systems: 
computing time for a job step or 
cataloged procedure step, and main 
storage region size. 
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5. Compiler, linkage editor, or loader 
options chosen for the job step. 

Figure 5 is the general format of the 
EXEC statement. 

Note ; If the information specified is 
normally delimited by parentheses but 
contains blanks, parentheses, or equal 
signs, it must be delimited by single 
quotation marks instead of parentheses. 



Identifying the Step (stepname) 



the EXEC statement identifies it with the 
PROC parameter, in place of the PGM 
parameter. 

1. Temporary libraries are temporary 

partitioned data sets created to store 
a program until it is used in a later 
job step of the same job. This type 
of library is particularly useful for 
storing the program output of a 
linkage editor run untiji. it is 
executed in a later job step. To 
execute a program from a temporary 
library, code the positional parameter 
in the first position of the operand 
field of the EXEC statement. 



The stepname identifies a job step 
within a job. It must satisfy the 
positional, length, and content 
requirements for a name field. The 
programmer must specify a stepname if later 
control statements refer to the step or if 
the step is going to be part of a cataloged 
procedure. Each stepname in a job or 
procedure must be unique. 



PGM=*. stepname. ddname 



The asterisk (*) indicates the current 
job step. Replace the terms stepname 
and ddname with the names of the job 
step and the DD statement within the 
procedure step, respectively, in which 
the temporary library is created. 



POSITIONAL PARAMETERS 



I dentifying the P rogr am (PGM) or Proc edure 
(PROC) 



The EXEC statement identifies the 
program to be executed in the job step with 
the PGM parameter. To specify the COBOL 
compiler, code the positional parameter in 
the first position of the operand field of 
the EXEC statement. 



If the temporary library is created in 
a catalogued procedure step, in order 
to call it in a later job step outside 
the procedure, give both the name of 
the job step that calls the procedure 
and the procedure stepname by coding 
the positional parameter in the first 
position of the operand field of the 
EXEC statement. 



PGM=*. stepname. procstepname. ddname | 

j 



PGM=IKFCBL00 



It indicates that the COBOL compiler is the 
processing program to be executed in the 
job step. 

To specify the linkage editor, code the 
positional parameter in the first position 
of the operand field of the EXEC statement. 



PGM=IEWL 



This indicates that the linkage editor is 
the processing program to be executed in 
the job step. 

The PGM parameter depends upon the type 
of library in which the program resides. 
If the job step uses a cataloged procedure, 



2. The system library is a partitioned 
data set named SYSl. LINKLIB that 
contains nonresident control program 
routines, and processor programs. To 
execute a program that resides in the 
system library, code the positional 
parameter in the first position of the 
operand field. 



PGM=progname 



Replace the term progname with the 
member name or alias associated with 
this program. This same keyword 
parameter can be used to execute a 
program that resides in a private 
library . Private libraries are made 
available to a job with a special DD 
statement (see "Additional DD 
Statement Facilities"). 
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T T 

Oper- 
ation 



Name 



Operand 



//[stepname] x 



EXEC 



Positional Parameter s 

PGM=progname 

PGM=*. stepname, ddname 

PROC=procname 

procname 

PGM=*. stepname. procstep. ddname 

Keyw ord Parameters 

JACCT 2 ) a i+ s 

JACCT.procstepf = (accounting-information) 

jcOND 2 ) 

|cOND.procstep( = ( (code, operator [, stepname [.procstep] ])... ) 

JPARM 2 

jPARM. procstep^ = (option t , option] . > . ) 

JTIME 

/TIME. procstep} = (minutes, seconds) 

(region 

JREGION. procstep^ = nnnnnxK [ , nnnnnyK] 

JROLL 

/ROLL, procstep \ = (x, y) 



|rd. 



IRD. procstep^ = request 

Idprty / 

JDPRTY. procstep^ = (value 1, value 2) 



^-Stepname is required when information from this control statement is referred to in a 

later job step. 
2 If this format is selected, it may be repeated in the EXEC statement once for each 

step in the cataloged procedure. 
3 If the information specified contains any special characters except hyphens, it must 

be delimited by single quotation marks instead of parentheses. 
**If accounting-information contains any special characters except hyphens, it must be 

delimited by single quotation marks. 
5 The maximum number of characters allowed between the delimiting quotation marks or 

parentheses is 142. 
•The maximum number of repetitions allowed is 7. 

T If only one test is specified, the outer pair of parentheses may be omitted. 
8 If the only special character contained in the value is a comma, the value may be 

enclosed in quotation marks. 
'The maximum number of characters allowed between the delimiting quotation marks or 

parentheses is 100. 



Figure b. EXEC Statement 
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3. Instead of executing a particular 
program, a job step may use a 
cataloged proced ure . A cataloged 
procedure can contain control 
statements for several steps, each of 
which executes a particular program. 
Cataloged procedures are members of a 
library named SYSl. PROCLIB. To 
reguest a cataloged procedure, code 
the positional parameter in the first 
position of the operand field of the 
EXEC statement. 



keyword parameter in the operand field of 
the EXEC statement. 



r 1 

| ACCT. procstep=( accounting information) j 
l J 



Procstep is the name of the step in the 
cataloged procedure. This specification 
overrides the ACCT parameter in the named 
procedure step, if one is present. 



PROC=procname 



Specifying Conditions for Bypas sing or 
Executing the Job Step (COND) 



Replace the term procname with the 
ungualified name of the cataloged 
procedure (see "Using the DD 
Statement" for a discussion of 
gualified names). 

Note : A procedure may be tested before it 
is placed in the procedure library by 
converting it into an in-stream procedure 
and placing it within the job step itself. 
In-stream procedures are discussed in the 
section, "Testing a Procedure as an 
In-Stream Procedure" in the chapter "Using 
the Cataloged Procedures. " 



KEYWORD PARAMETERS 



The execution of certain job steps is 
based on the success or failure of 
preceding steps. The COND parameter 
provides the means to: 

• Make as many as eight tests on return 
codes issued by preceding job steps or 
cataloged procedure steps, which were 
completed normally. If any one of the 
tests is satisfied, the job step is 
bypassed. 

• Specify that the job step is to be 
executed even if one or more of the 
preceding job steps abnormally 
terminated or only if one or more of 
the preceding job steps abnormally 
terminated. 



Spec ifying Job Step Accounting Inf orm ation 
(ACCT) 



When executing a multistep job, or a job 
that uses cataloged procedures, the 
programmer can use this parameter so that 
jobsteps are charged to separate accounting 
areas. To specify items of accounting 
information to the installation accounting 
routines for this job step, code the 
keyword parameter in the operand field of 
the EXEC statement. 



ACCT=( accounting information) 



To specify conditions for bypassing a 
job step, code the keyword parameter in the 
operand field of the EXEC statement. 

r 1 

| COND=( (code, operator, [stepname] ),... , | 
j (code, operator, [stepname] ) ) j 

L J 



The term "code" may be replaced by a 
decimal numeral to be compared with the job 
step return code. The return codes for 
both the compiler and the linkage editor 
are: 

00 Normal conclusion 



Replace the term "accounting information" 
with one or more subparameters separated by 
commas. If both the JOB and EXEC 
statements contain accounting information, 
the installation accounting routines decide 
how the accounting information shall be 
used for the job step. 



To pass accounting information to a step 
within a cataloged procedure, code the 



04 Warning messages have been listed, 
but program is executable. 

08 Error messages have been listed; 
execution may fail. 

12 Severe errors have occurred; 
execution is impossible. 

16 Terminal errors have occurred; 

execution of the processor has been 
terminated. 
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The compiler issues a return code of 16 
when any of the following are detected: 



• BASIS member-name is specified and no 
member of that name is found 



• COPY member-name is specified and no 
SYSLIB statement is included 



• Required device not available 



• Not enough core storage is available 
for the tables required for compilation 

• A table exceeded its maximum size 

• A permanent input/output error has been 
encountered on an external device 



The return codes have a correlation with 
the severity level of the error messages. 
With linkage editor messages, for example, 
the rightmost digit of the message number 
states the severity level; this number is 
multiplied by 4 to get the appropriate 
return code. With the COBOL compiler, 04, 
08, 12, and 16 are equal to the severity 
flags: W, C, E, and D, respectively. 

The term "operator" specifies the test 
to be made of the relation between the 
programmer-specified code and the job step 
return code. Replace the term operator 
with one of the following: 

GT (greater than) 

GE (greater than or equal to) 

EQ (equal to) 

LT (less than) 

LE (less than or equal to) 

NE (not equal to) 



The term "stepname" identifies the 
previously executed job step that issued 
the return code to be tested and is 
replaced by the name of that preceding job 
step. If stepname is not specified, code 
is compared to the return codes issued by 
all preceding steps in the job. 

Replace the term stepname with the name 
of the preceding job step that issues the 
return code to be tested. 

If the programmer codes 

COND= ( ( 4 , GT, STEP1 ) , ( 8 , EQ, STEP2 ) ) 

the statement is interpreted as: "If 4 is 
greater than the return code issued by 
STEP1, or if STEP2 issues a return code of 
8, this job step bypassed." 



Notes : 



If only one test is made, the 
programmer need not code the outer 
parentheses, e.g., COND=(12,EQ, STEPX) . 

If each return code test is made on all 
preceding steps, the programmer need 
not code the terms stepname, e. g. , 
COND=((4,GT), (8,EQ)). 

When the return code is issued by a 
cataloged procedure step, the 
programmer may want to test it in a 
later job step outside of the 
procedure. In order to test it, give 
both the name of the job step that 
calls the procedure and the procedure 
stepname, e.g., COND=( (code, operator, 
stepname. procstep) ,...). 



Abnormal termination of a job step 
normally causes subsequent steps to be 
bypassed and the job to be terminated. By 
means of the COND parameter, however, the 
programmer can specify execution of a job 
step after one or more preceding job steps 
have abnormally terminated. For the COND 
parameter, a job step is considered to 
terminate abnormally if a failure occurs 
within the user's program once it has 
received control, (If a job step is 
abnormally terminated during scheduling 
because of failures such as job control 
language errors or inability to allocate 
space, the remainder of the job steps are 
bypassed, whether or not a condition for 
executing a later job step was specified. ) 

To specify the condition for executing a 
job step, code the keyword parameter in the 
operand field of the EXEC statement. 



COND= 



EVEN 



ONLY 



The EVEN or ONLY subparameters are mutually 
exclusive. The subparameter selected can 
be coded in combination with up to seven 
return code tests, and can appear before, 
between, or after return code tests, e,g,, 

COND=(EVEN, (4,GT,STEP3) ) 

COND=( (8, GE, STEP1) , (16, GE) , ONLY) 



The EVEN subparameter causes the step to 
be executed even when one or more of the 
preceding job steps have abnormally 
terminated. However, if any return code 
tests specified in this job step are 
satisfied, the step is bypassed. The ONLY 
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subparameter causes the step to be executed 
only when one or more of the preceding job 
steps have abnormally terminated. However, 
if any return code tests specified in this 
job step are satisfied, the step is 
bypassed. 

When a job step abnormally terminates, 
the COND parameter on the EXEC statement of 
the next step is scanned for the EVEN or 
ONLY subparameter. If neither is speci- 
fied, the job step is bypassed and the EXEC 
statement of the next step is scanned for 
the EVEN or ONLY subparameter. If EVEN or 
ONLY is specified, return code tests, if 
any, are made on all previous steps 
specified that executed and did not 
abnormally terminate. If any one of these 
tests is satisfied, the step is bypassed. 
Otherwise, the job step is executed. 

If the programmer codes 

COND=EVEN 

the statement is interpreted as: "Execute 
this step even if one or more of the 
preceding steps abnormally terminated 
during execution." If COND=ONLY is coded, 
it is interpreted as: "Execute this step 
only if one or more of the preceding steps 
abnormally terminated during execution. " 

If the COND parameter is omitted, no 
return code tests are made and the step 
will be bypassed when any of the preceding 
job steps abnormally terminate. 



Notes: 



When a job step that contains the EVEN 
or ONLY subparameter refers to a data 
set that was to be created or cataloged 
in a preceding step, the data set will 
not exist if the step creating it was 
bypassed. 

When a jobstep that contains the EVEN 
or ONLY subparameter refers to a data 
set that was to be created or cataloged 
in a preceding step, the data set may 
be incomplete if the step creating it 
abnormally terminated. 

When the job step uses a cataloged 
procedure, the programmer can establish 
return code tests and the EVEN or ONLY 
subparameter for a procedure step by 
including, as part of the keyword COND, 



the procedure stepname, e.g., 
COND. procstepname. This specification 
overrides the COND parameter in the 
named procedure step if one is present. 
The programmer can code as many 
parameters of this form as there are 
steps in the cataloged procedure. 



To establish one set of return code 
tests and the EVEN or ONLY subparameter 
for all steps in a procedure, code the 
COND parameter without a procedure 
stepname. This specification replaces 
all COND parameters in the procedure if 
any are present. 



Job steps following a step that 
abnormally terminates are normally 
bypassed. If a job step is to be executed 
even if a preceding step abnormally 
terminates, specify this condition, along 
with up to seven return code tests: 



|//STEP3 EXEC PGM=CONVERT, 

|// COND=(EVEN, (4,EQ,STEP1) >, . .. 



Here, the step is executed if the return 
code test is not satisfied, even if one or 
more of the preceding job steps abnormally 
terminated. If a job step is to execute 
only when one or more of the preceding 
steps abnornally terminate, replace EVEN in 
the above example with ONLY. 

If the EXEC statement calls a cataloged 
procedure, the programmer can establish 
return code tests and the EVEN or ONLY 
subparameter for a procedure step by coding 
the COND parameter followed by the name of 
the procedure step to which it applies: 

r 1 

|//STEP4 EXEC ANALYSIS, COND. X| 
|// REDUCE=( < 16, EQ, STEP4. LOOKUP), ONLY), . . . | 
L J 



Here, the cataloged procedure step named 
REDUCE will be executed only if a preceding 
job step has abnormally terminated and the 
procedure step named LOOKUP does not issue 
a return code of 16. The programmer can 
code as many COND parameters of this type 
as there are steps in the procedure. 



Pass in g Informati on to the Pr ocessing 
P rog ram (PARM) 



For processing programs that require 
control information at the time they are 
executed, the EXEC statement provides the 
PARM parameter. To pass information to the 
program, code the keyword parameter in the 
operand field. 



pAkM= ( option [ , option ] . . . > 



This will pass options to the compiler, 
linkage editor, loader, or object program 
when any one of them is called by the PGM 
parameter in the EXEC statement or to the 
first step in a cataloged procedure. 



To pass options to a compiler, the 
linkage editor, loader, or the execution 
step within the named cataloged procedure 
step, code the keyword parameter in the 
operand field. 



Table 2. Significant Characters for 
Various Options 



PARM. procstep= ( option [ , option] . . . ) j 



Any PARM parameter already appearing in the 
procedure step is deleted, and the PARM 
parameter that is passed to the procedure 
step is inserted. 



A maximum of 100 characters may be 
written between the parentheses or single 
quotation marks that enclose the list of 
options. The COBOL compiler selects the 
valid options of the PARM field for 
processing by looking for three significant 
characters of each key option word. When 
the keyword is identified, it is checked 
for the presence or absence of the prefix 
NO, as appropriate. The programmer can 
make the most efficient use of the option 
field by using the significant characters 
instead of the entire option. Table 2 
lists the significant characters for each 
option (see "Options for the Compiler" for 
an explanation of each). 









l 






Significant 






Option 


Characters 




L 






j 


r 


T 


1 




LINECNT 


CNT 






SEQ 


SEQ 






FLAGE(W) 


LAG, LAGW 






SIZE 


SIZ 






BUF 


BUF 






SOURCE 


SOU 






DECK 


DEC 






t r\T\ r\ 


t r>,7\ 






±j<Jt\U 








SPACE 


ACE 






DMAP 


DMA 






PMAP 


PMA 






SUPMAP 


SUP 






CLIST 


CLI 






TRUNC 


TRU 






APOST 


APO 






QUOTE 


QUO 






XREF 


XRE 






BATCH 


BAT 






NAME 


NAM 






SXREF 


SXR 






STATE 


STA 






TERM 


TER 






NUM 


NUM 






FLOW 


FLO 






LIB 


LIB 






SYMDMP 


SYM 






OPTIMIZE 


OPT 






SYNTAX 


SYN 






CSYNTAX 


CSY 






RESIDENT 


RES 






DYNAM 


DYN 






SYSx 


SYS 






VERB 


VER 






ZWB 


ZWB 





Options for the Compiler 



The IBM-supplied default options 
indicated by an underscore in the following 
discussion can be changed when the compiler 
is installed. The format of the PARM 
parameter is illustrated in Figure 6. 

Notes : 

• When a subparameter contains an equal 
sign, the entire information field of 
the PARM parameter must be enclosed by 
single quotation marks instead of 
parentheses, e.g., 

PARM=' SIZE=160000, PMAP* . 

• When an option and its default (such as 
XREF and NOXREF) are both specified, 
the last encountered option is 
generally the one assumed. (Exceptions 
to this rule are cited in the option 
descriptions. ) Accordingly, the 
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programmer may change one of the many 
options without repunching the entire 
EXEC card. 

SIZE=yyyyyyy 

indicates the amount of main storage, 
in bytes, available for compilation 
(see "Machine Considerations"). 

BUF=yyyyyy 

indicates the amount of main storage 
to be allocated to buffers. If both 
SIZE and BUF are specified, the amount 
allocated to buffers is included in 
the amount of main storage available 
for compilation (see "Appendix D: 
Compiler Optimization" for information 
about how buffer size is determined). 

Note : The SIZE and BUF compile-time 
parameters can be given in multiples of K, 
where K=1024 decimal bytes. For example, 
80K is 81,920 decimal bytes. 

SOURCE 
NOSOURCE 

indicates whether or not the source 

module is to be listed. 



CLIST 

NOCLIST 

indicates whether or not a condensed 
listing is to be produced. If 
specified, the procedure portion of 
the listing will contain generated 
card numbers (unless the NUM option is 
in effect) , verb references, and the 
location of the first instruction 
generated for each verb. Global 
tables, literal pools, register 
assignments, and information about the 
Working- Storage Section are also 
provided. CLIST and PMAP are mutually 
exclusive options. 

Note : In nonsegmented programs, verbs are 
listed in source order. In segmented 
programs, the root segment is last. (For 
programs run with the OPTIMIZE option the 
root segment is first, followed by the 
individual segments in order of ascending 
priority. ) 



Working-Storage Section, and an 
assembler-language expansion of the 
source modules are to be listed. 
CLIST and PMAP are mutually exclusive 
options. 

Note: If any one of the options CLIST, 
DMAP, and PMAP is specified, the compiler 
will produce a message giving the 
hexadecimal length and starting address of 
the Working Storage Section. For an 
illustration of the use of these options, 
see the "Output" section. 

VERB 

NOVERB 

indicates whether procedure-names and 
verb-names are to be listed with the 
associated code on the object-program 
listing. VERB has meaning only if 
PMAP or CLIST is in effect. NOVERB 
yields more efficient compilation. 

LOAD 

NOLOAD 

indicates whether or not the object 
module is to be placed on a mass 
storage device or a tape volume so 
that the module can be used as input 
to the linkage editor. If the LOAD 
option is used, a SYSLIN DD statement 
must be specified. 



DECK 

NODECK 

indicates whether or not the object 
module is to be punched. If the DECK 
option is used, a SYSPUNCH DD 
statement must be specified. 



SEQ 

NOSEQ 

indicates whether or not the compiler 
is to check the sequence of the source 
module statements. If the statements 
are not in sequence, a message is 
printed. 

Note: For examples of what the SOURCE, 
DMAP, PMAP, and SEQ options produce, see 
"Output. " 



DMAP 

NODMAP 

indicates whether or not a glossary is 
to be listed. Global tables, literal 
pools, register assignments, and 
information about the Working-Storage 
Section are also provided. 

PMAP 

NOPMAP 

indicates whether or not register 
assignments, global tables, literal 
pools, information about the 



LINECNT=nn 

indicates the number of lines to be 
printed on each page of the 
compilation source card listing. The 
number specified by nn must be a 
2-digit integer from 01 to 99. If the 
LINECNT option is omitted, 60 lines 
are printed on each page of the output 
listing. 

Note: The compiler allows for 
headings three lines of what the user 
has specified. (For example, if nn=55 



is specified, then 52 lines are 
printed on each page of the output 
listing. ) 



item is dependent on the size of the 
field (half word, fullword). 



ZWB 
NOZWB 



indicates whether or not the compiler 
generates code to strip the sign from 
a signed external decimal field when 
comparing this field to an 
alphanumeric field. If ZWB is 
specified, the signed external decimal 
field is moved to an intermediate 
field, in which its sign is removed, 
before it is compared to the 
alphanumeric field. ZWB complies with 
the ANS standard; NOZWB should be used 
when, for example, input numeric 
fields are to be compared with SPACES. 



Note: The default option cannot be changed 
when the compiler is installed. 



QUOTE 
APOST 



FLAGW 
FLASE 



indicates the type of messages that 
are to be listed for the compilation. 
FLAGW indicates that all warning and 
diagnostic messages are to be listed. 
FLAGE indicates that all diagnostic 
messages are to be listed, but that 
the warning messages are not to be 
listed. 



SUPMAP 

NOSUPMAP 

indicates whether or not the object 
code listing, and object module and 
link edit decks are to be suppressed 
if an E- level or D-level message is 
generated by the compiler. 



SPACE1 

SPACE2 

SPACE3 

indicates the type of spacing that is 
to be used on the source card listing 
generated when SOURCE is specified. 
SPACE1 specifies single spacing, 
SPACE2 specifies double spacing, and 
SPACE3 specifies triple spacing. 



TRUNC 

NOTRUNC 

applies to movement of COMPUTATIONAL 
arithmetic fields. If TRUNC (standard 
truncation) is specified and the 
number of digits in the sending field 
is greater than the number of digits 
in the receiving field, the arithmetic 
item is truncated to the number of 
digits specified in the PICTURE clause 
of the receiving field when moved. If 
NOTRUNC is specified, movement of the 



indicates to the compiler that either 
the double quote (") or the apostrophe 
( ' ) is acceptable as the character to 
delineate literals and to use that 
character in the generation of 
figurative constants. 



STATE 

NOSTATE 

indicates whether or not the number of 
the COBOL statement being executed at 
the time of an abnormal termination is 
desired. STATE identifies the number 
of the statement and the number of the 
verb oeing executed. If the STATE 
option is used, a SYSDBOUT DD 
statement must be specified at 
execution time for the output data set 
on which the statement number message 
can be written. For more information, 
see "Debugging Facilities" in the 
chapter "Program Checkout. " 



FLOW[=nn] 

NOFLOW 

indicates whether or not a formatted 
trace is desired for a variable number 
of procedures executed before an 
abnormal termination. The number of 
procedures traced is specified by nn, 
where nn may be any integer value from 
one to 99. FLOW[=nn] must be 
specified at compile time to generate 
the necessary trace linkage; however, 
specifying nn may be deferred until 
execution time. If nn is omitted, 
thedefault value is employed. This 
value is either 99 or that specified 
at program product installation. 
Specifying NOFLOW at compile time 
precludes specification of the Flow 
Trace option at execution time. A 
SYSDBOUT DD statement must be included 
for the output data set on which the 
trace can be written. See "Options 
for Execution" for more information. 



SYMDMP 

NOSYMDMP 

requests a formatted dump of the data 
area of the object program at abnormal 
termination. With this option, the 
programmer may request dynamic dumps 
of specified data-names at strategic 
points during program execution. 
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Notes : 

1. If the SYMDMP option is in effect, 
the SYSUT5 data set must be 
specified. 

2. If the BATCH option is requested, 
symbolic debugging is rejected. 

3. Specification of the SYMDMP option 
automatically yields the OPTIMIZE 
feature, discussed below, and 
rejects the STATE option because 
SYMDMP output includes STATE 
output at abnormal termination. 



If both SYNTAX and OPTIMIZE are 
specified, no object code is 
produced. 



Unconditional syntax checking is 
assumed if all of the following 
compile-time options are 
specified: 



NOLOAD 
NOXREF 
NOSXREF 



NOCLIST 
NOPMAP 



SUPMA.P 
NODECK 



For a discussion of the FLOW, STATE, and 
SYMDMP options, and their value to the 
COBOL programmer, see the chapter entitled 
"Symbolic Debugging Features. " A SYSDBOUT, 
SYSDBG, and debug file DD codes are 
required at execution time. 



OPTIMIZE 

NOOPTIMIZE 

causes optimized object code to be 
generated by the compiler, 
considerably reducing the use of 
object program main storage. In 
general, the greater the number of 
COBOL Procedure Division source 
statements, the greater the percentage 
of reduction in the amount of main 
storage required. 

Note : The optimizer feature is 
automatically in effect when the 
SYMDMP feature is specified. 

SYNTAX 

CSYNTAX 

NOSYNTAX 

indicates whether the source text is 
to be scanned for syntax errors only 
and appropriate error message are to 
be generated. For conditional syntax 
checking (CSYNTAX), a full compilation 
is produced so long as no messages 
exceed the W or C level. If one or 
more E-level or higher severity 
messages are produced, the compiler 
generates the messages but does not 
generate object text. 



Notes: 



When the SYNTAX option is in 
effect, all of the following 
compile-time options are 
suppressed: 



LOAD 


PMAP 


FLOW 


XREF 


DECK 


STATE 


SXREF 


SYMDMP 


NAME 


CLIST 


TRUNC 


RESIDENT 


NOSUPMAP 


OPTIMIZE 





NUM 

NONUM 

indicates whether or not line numbers 
have been recorded in the input and, 
rather than compiler-generated source 
numbers, should be used in error 
messages, as well as in PMAP, CLIST, 
STATE, XREF, SXREF, and FLOW. NONUM 
indicates that the compiler-generated 
numbers should be used in error 
messages as well as in PMAP, CLIST, 
STATE, XREF, SXREF, and FLOW. 

Note : If when the NUM option is in 
effect the compiler discovers a 
non-numeric character in a line number 
or if ascending numeric sequence is 
broken and one or more of the 
debugging options are in effect, the 
compiler invalidates the number. The 
compiler then takes the last valid 
card number in sequence, adds a 1 to 
that number and begins generating card 
numbers from that point. The 
increment is 1. Six digits is the 
maximum sequence number. The card 
that follows 999999 will be flagged 
and NUM, SYMDMP, and test cancelled. 
STATE and FLOW will not be cancelled. 

XREF 

NOXREF 

indicates whether or not a 
cross-reference listing is produced. 
If XREF is specified, an unsorted 
listing is produced with data-names 
and procedure-names appearing in two 
parts in source order. 



SXREF 
NOSXREF 



indicates whether or not a sorted 
cross-reference listing is produced, 
If SXREF is specified, a sorted 
listing is produced with data-names 
and procedure-names in alphanumeric 
order. 



Note : XREF and SXREF are mutually 



exclusive. 
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LIB 
NOLIB 



indicates whether or not a COPY and/or 
a BASIS request will be part of the 
COBOL source input stream. If no 
library facilities are to be used, the 
specification of NOLIB will save 
compilation time, because it avoids 
the opening of the SYSLIB data set. 



BATCH 

NOBATCH 

indicates whether or not multiple 
programs and/or subprograms are to be 
compiled with a single invocation of 
the compiler. In the BATCH 
environment all compiler options 
specified on the EXEC card, plus all 
default options, will apply to every 
program in the batch unless specific 
options are overridden on the CBL 
card, which must be included for each 
program. See "Batch Compilation" for 
more information on batch compilations 
and the CBL card. 



NAME 

NONAME 

indicates whether or not programs in a 
batch compilation environment will be 
link-edited into one or more load 
modules. If NAME is specified, each 
succeeding program in the batch will 
be link-edited into a separate load 
module. This option will remain in 
effect for the entire compilation 
unless NONAME is specified on the CBL 
card for an individual program. If 
NONAME is specified on the CBL card, 
no name will be generated for this 
compilation. Names for the load 
modules will be formed according to 
the rules for forming module names 
from the PROGRAM-ID. See "Batch 
Compilation" for more details on batch 
compilation and the CBL card. 

Note : If the BATCH option is not 
specified, NONAME will be in effect. 

RESIDENT 

NORESIDENT 

requests the COBOL Library Management 
feature. When one program in a given 
region/partition requests the RESIDENT 
option, the main program and all 
subprograms in that region/partition 
should also request it. 

Note : The RESIDENT option is 
automatically in effect when the DYNAM 
option is invoked. 

DYNAM 
NODYNAM 

causes subprograms invoked through the 



SYST 
SYSx 



CALL literal statement to be 
dynamically loaded and through the 
CANCEL statement to be dynamically 
deleted at object time (instead of 
link-edited with the calling program 
into a single load module). 

Note: When both NORESIDENT and 
NODYNAM are either specified or 
implied by default, and a CALL 
identifier statement occurs in the 
source statement being compiled, the 
COBOL Library Management Facility 
option (RESIDENT) is automatically in 
effect. A printed statement of this 
is given in the compiler output. (For 
a discussion of the COBOL Library 
Management Facility, see the section 
"Sharing COBOL Library Subroutines" in 
the "Libraries" chapter. ) 



indicates whether SYSOUT or SYSOUx, 
where x must be alphanumeric (that is, 
0-9 or A-Z except for T) , is the 
ddname of the file to be used for 
debug output and for data when SYSOUT 
is specified, either implicitly or 
explicitly, in a DISPLAY statement. 
The specification in the program that 
is first to access the file is chosen. 



Options for Use Only Unde r TSO 



In addition to the preceding compiler 
options, the following options are designed 
for use with the Time Sharing Option (TSO). 
Time Sharing provides the COBOL programmer 
with facilities for entering, compiling, 
and testing programs at his terminal. (For 
further information on the Time Sharing 
Option, see the Program Product publication 

I § M .-0? iH§Q2.1 COBOL Prompter User's Guide 

and Reference. ) These options are listed 
in Figure 6, where: 



PRINT 



(*) 



(dsname) 



NOPRINT 



indicates whether or not the program 
listing is to be suppressed, placed on 
the output data set specified by 
dsname, or displayed at the terminal. 
If PRINT is specified, the listing 
will include page headings, line 
numbers of the statements in error, 
message identification numbers, 
severity levels, and message texts (as 
well as any other output requested by 
SOURCE, CLIST, DMAP, PMAP, XREF, or 
SXREF). If (*) is specified instead 
of data-set name, the printed output 
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is sent to the terminal. If PRINT 
alone is specified, a listing data set 
is created on secondary storage and 
named according to standard data set 
naming conventions. NOPRINT specifies 
that no listing is to be printed. If 
neither PRINT nor NOPRINT is specified 
and any one or more of the options 
SOURCE. CLIST, DMAP, XREF ? or PMAP are 
specified, PRINT is the default. 
Otherwise, NOPRINT is the default. If 
PRINT is specified in a non-TSO 
environment, it is ignored. 



TERM 

NOTERM 

indicates whether or not progress and 
diagnostic messages are to be printed 
on the SYSTERM terminal data set. The 
severity level of the messages may be 
controlled by the FLAG option. If 
PRINT (*) is specified, then NOTERM is 
the default, to ensure that messages 
appear only once. If TERM is 
specified in a non-TSO environment, 
the output that normally goes to the 
SYSTERM DD data set is written on the 
SYSTERM file if a SYSTERM DD card has 
been included. If there is no SYSTERM 
DD card, a warning message is issued. 



LIST 



OVLY 



indicates that any linkage editor 
control statements associated with the 
job step are to be listed. 



indicates that the load module is to 
be in the format of an overlay 
structure. This option is required 
when the COBOL Segmentation feature is 
used. 



The format of the PARM parameter is 
illustrated in Figure 6. For examples of 
what the MAP, XREF, and LIST options 
produce, see "Output." Linkage editor 
control statements and overlay structures 
are explained in "Calling and Called 
Programs. " There are other PARM options 
for linkage editor processing that describe 
additional processing options and special 
attributes of the load module (see the 
publication IBM OS Linkage Editor and 
Loader) . 



Opt ions for thg Loader- 



Options for the Li n kage Editor 



MAP 



indicates that a map of the load 
module is to be listed. If MAP is 
specified, XREF cannot be specified, 
but both can be omitted. 



MAP 
NOMAP 



indicates whether or not a map of the 
loaded module is to be produced that 
lists external names and their 
absolute addresses on the SYSPRINT 
data set. If the SYSPRINT DD 
statement is not used in the input 
deck, this option is ignored. An 
example of a module map is shown in 
"Output. " 



XREF 



indicates that a cross-reference list 
and a module map are to be listed. If 
XREF is specified, MAP cannot be 
specified. 
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Compiler: 
\PARM 
/ PARM. procstep) 



= ( [SIZE=yyyyyyy] [ , BUF=yyyyyy] 



t SOURCE 
NOSOURCE 



, DMAP 
. NOD MAP 



,PMAP 
, NOPMAP 



, SUPMAP 
, NOSUPMAP 

7TRUNC 
. NOTRUNC 



. SPACE1 
, SPACE2 
, SPACE 3 



, BATCH 
. NOBATCH 
, SYMDMP 
. NOSYMDMP 



. L OAD 
, NOLOAD 

, CLIST 
, NOCLIST 
7 STATE _ 
. NOSTATE 



,DECK 
. NODECK 



«§E2 
, NOSEQ 



[,LINECNT=nn] 



f FLAGW 
, FLAGE 
7XREF 
, NOXREF 



17 RESIDENT 
NORESIDENT 



t 



, FLOW[=nn] 
t NOFLOW 
, OPTIMIZE 
. NO OPTIMIZE 



» DYNAM 
. NODYNAM 



, TERM "1 *» 
, NOTERM 
7 SYNTAX 
, CSYNTAX 
NOSYNTAX 



. QUOTE 

. APOST 

, SXREF I , NAME 

, NOSXREF , NONAME 



, PRINT < 
1 NOPRINT 



jdsname) 



,VERB 
, NOVERB 



r 



c 



,ZWB 
NOZWB 



SYST 
,SYSx 



Linkage Editor: 
PARM / 
PARM. procstep\ 



= ( 



(map 

(XREF 



[,LIST] [,OVLY]> 



Loader : 

(PARM ) 

/ PARM. procstepl 



= ( 



MAP 
NOMAP 



, RES 
, NORES 



. CALL 
, NOCALL 



,LET 
. NOLET 



, SIZE=100K 
, SIZE=size 



Execution: 



JPARM 

fPARM. procstepj 



[,EP=name] 



=([user parameters] 



, PRINT 
, NOPRINT 

,FLOW[=nn] 
« NOFLOW 



x If the information specified contains any special characters, it must be delimited by 

single quotation marks instead of parentheses. 
2 If the only special character contained in the value is a comma, the value may be 

enclosed in parentheses or quotation marks. 
3 The maximum number of characters allowed between the delimiting quotation marks or 

parentheses is 100. 
**These options should be used in the Time Sharing environment only. 
5 TSO-only format. 
l 

Figure 6. Compiler, Linkage Editor, and Loader PARM Options 



Job Control Procedures 41 



RES 

NORES 

indicates whether or not an automatic 
search of the link pack area queue is 
to be made. This search is always 
made after processing the primary 
input (SYSLIN), and before searching 
the SYLIB data set. When the RES 
option is specified, the CALL option 
is automatically set. 

CALL 

NOCALL (NCAL) 

indicates whether or not an automatic 
search of the SYSLIB data set is to be 
made. If the SYSLIB DD statement is 
not used in the input deck, this 
option is ignored. The NOCALL option 
causes an automatic NORES. 



LET 

NOLE T 

indicates whether or not the loader 
will try to execute the object program 
when a severity level 2 error 
condition is found. 

SIZE^IOOK 

SIZE=size 

specifies the size, in bytes, of 
dynamic main storage that can be used 
by the loader. This storage must be 
large enough to accommodate the object 
program. 

EP=name 

specifies the external name to be 
assigned as the entry point of the 
loaded program. 

PRIN T 

NOPRINT 

indicates whether or not diagnostic 
messages are to be produced on the 
SYSLOUT data set. 

The format of the PARM parameter is 
illustrated in Figure 6. The default 
options, indicated by an underscore, can be 
changed at system generation with the 
LOADER macro instruction. 



Options for Execution 



Note : The programmer may want to include 
additional user parameters in the PARM 
field for the execution step of his job. 
These parameters are discussed below. 



names, at execution time a value for 
nn may be specified that overrides any 
value set at compile time. If FLOW is 
requested at compile time with no 
value for nn, a value should be 
specified at execution time. A 
default of 99 is assumed for nn if it 
is not specified at either step and 
FLOW is in effect; otherwise, nn is as 
previously specified. When specified 
at execution time, FLOW must be the 
last option in the PARM field. (The 
format of the PARM parameter is 
illustrated in Figure 6. ) 

The FLOW trace may be suppressed at 
execution time by specifying NOFLOW. 
FLOW cannot be specified as an option 
for execution if it is not specified 
at compile time or if NOFLOW is in 
effect by default. See the sections 
"Debugging Facilities" and "Options 
for the Compiler" for additional 
information. 



Requesting Restart for a Job Step (RD) 



The restart facilities can be used in 
order to minimize the time lost in 
reprocessing a job that abnormally 
terminates. These facilities permit the 
automatic restart of jobs that were 
abnormally terminated during execution. 

The programmer uses this parameter to 
tell the operating system: (1) whether or 
not to take checkpoints during execution of 
a program, and (2) whether or not to 
restart a program that has been 
interrupted. 

A checkpoint is taken by periodically 
recording the contents of storage and 
registers during execution of a program. 
The RERUN clause in the COBOL language 
facilitates taking checkpoint readings. 
Checkpoints are recorded onto a checkpoint 
data set. 

Execution of a job can be automatically 
restarted at the beginning of a job step 
that abnormally terminated (step restart) 
or within the step (checkpoint restart). 
In order for checkpoint restart to occur, a 
checkpoint must have been taken in the 
processing program prior to abnormal 
termination. The RD parameter specifies 
that step restart can occur or that the 
action of the CHKPT macro instruction is to 
be suppressed. 



FLOW[=nn] 

NOFLOW 

If the FLOW option is specified at 
compile time for a trace of procedure 



To request that step restart be 
permitted or to request that the action of 
the CHKPT macro instruction be suppressed 
in a particular step, code the keyword 



uz 



parameter in the operand field of the EXEC 
statement. 



However, a resubmitted job could have 
execution start at a specific checkpoint. 



RD=request 



Replace the word "request" with: 

R — to permit automatic step restart. 
The programmer must specify at 
least one RERUN clause in order 
to take checkpoints. 

NC — to suppress the action of the 
CHKPT macro instruction and to 
prevent automatic restart. No 
checkpoints are taken; no RERUN 
clause in the COBOL program is 
necessary. 

NR — to request that the CHKPT macro 
instruction be allowed to 
establish a checkpoint, but to 
prevent automatic restart. The 
programmer must specify at least 
one RERUN clause in order to take 
checkpoints. 

RNC — to permit step restart and to 

suppress the action of the CHKPT 
macro instruction. No 
checkpoints are taken; no RERUN 
clause in the COBOL program is 
necessary. 



Before automatic step restart occurs, 
all data sets in the restart step with a 
status of OLD or MOD, and all data sets 
being passed to steps following the restart 
step, are kept. All data sets in the 
restart step with a status of NEW are 
deleted. Before automatic checkpoint 
restart occurs, all data sets currently in 
use by the job are kept. 



If the RD parameter is omitted and no 
CHKPT macro instructions are executed, 
automatic restart cannot occur. If the RD 
parameter is omitted but one or more CHKPT 
macro instructions are executed, automatic 
checkpoint restart can occur. 



Notes : 



If the RD parameter is specified on the 
JOB statement, RD parameters on the 
job's EXEC statements are ignored. 



• Restart can occur only if MSGLEVEL=1 is 
coded on the JOB statement. 



• If step restart is requested for this 
step, assign the step a unique step 
name. 



Each request is described in greater detail 
in the following paragraphs. 



R D=R : If the processing programs used by 
this step do not include a RERUN statement, 
RD=R allows execution to be resumed at the 
beginning of this step if it abnormally 
terminates. If any of these programs do 
include one or more CHKPT macro 
instructions (through the use of the RERUN 
clause), step restart can occur if this 
step abnormally terminates before execution 
of a CHKPT macro instruction; thereafter, 
checkpoint restart can occur. 



RD=N C or RD=RNC : RD=NC or RD=RNC should be 
specified to suppress the action of all 
CHKPT macro instructions included in the 
programs used by this step. When RD=NC is 
specified, neither step restart nor 
checkpoint restart can occur. When RD=RNC 
is specified, step restart can occur. 



RD=N R: RD=NR permits a CHKPT macro 
instruction to establish a checkpoint, but 
does not permit automatic restarts. 



When this job step uses a cataloged 
procedure, make restart request for a 
single procedure step by including, as 
part of the RD parameter, the procedure 
stepname, i.e., RD.procstepname. This 
specification overrides the RD 
parameter in the named procedure step 
if one is present. Code as many 
parameters of this form as there are 
steps in the cataloged procedure. 



• To specify a restart request for an 
entire cataloged procedure, code the RD 
parameter without a procedure stepname. 
This specification overrides all RD 
parameters in the procedure if any are 
present. 

• If no RERUN clause is specified in the 
user's program, no checkpoints are 
written, regardless of the disposition 
of the RD parameter. 

Reference : 

• For detailed information on the 
checkpoint/restart facilities, see the 
pub 1 ica t i on IBM OS Supervis or Serv ices . 
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Priority Scheduling EX EC Pa rameters 



Estab lishing a Di spat ching Prio rity (DPRTY) 
(MVT only) 

The DPRTY parameter allows the 
programmer to assign to a job step, a 
dispatching priority different from the 
priority of the job. The dispatching 
priority determines in what sequence tasks 
use main storage and computing time. To 
assign a dispatching priority to a job 
step, code the keyword parameter in the 
operand field of the EXEC statement. 



DPRTY=( value 1, value 2) 



Both "value 1" and "value 2" should be 
replaced with a number from through 15. 
"Value 1" represents an internal priority 
value. "Value 2" added to "value 1" 
represents the dispatching priority. The 
higher numbers represent higher priorities. 
h default value of is assumed if no 
number is assigned to "value 1." A default 
value of 11 is assumed if no number is 
assigned to "value 2." 

Notes : 

• Whenever possible, avoid assigning a 
number of 15 to "value 1. " This number 
is used for certain system tasks. 

• If "value 1" is omitted, the comma must 
be coded before "value 2" to indicate 
the absence of "value 1," e.g., 
DPRTY=(,14). 

• If "value 2" is omitted, the 
parentheses need not be coded, e.g., 
DPRTY=12. 

• On an MVT system with time-slicing 
facilities, the DPRTY parameter can be 
used to make a job step part of a group 
of job steps to be time-sliced. The 
priorities of the time-sliced groups 
are selected at system generation. To 
cause the job step to be time-sliced, 
assign to "value 1" a number that 
corresponds to a priority number 
selected for time-slicing. "Value 2" 
is either omitted or assigned a value 
of 11. 

• When the step uses a cataloged 
procedure, a dispatching priority can 
be assigned to a single procedure step 
by including the procedure step name in 
the DPRTY parameter, i.e., 

DPRTY. procstepname=( value 1, value 2). 
This parameter may be used for each 
step in the cataloged procedure. 



To assign a single dispatching priority 
to an entire cataloged procedure, code 
the DPRTY parameter without a procedure 
step name. This specification 
overrides all DPRTY parameters in the 
procedure if there are any. 



Setting Job Step Ti me Limits (TI ME ) 



To assign a limit to the computing time 
used by a single job step, a cataloged 
procedure, or a cataloged procedure step, 
code the keyword parameter in the operand 
field of the EXEC statement. 



TIME= (minutes, seconds) 



Such an assignment is useful in a 
multiprogramming environment where more 
than one job has access to the computing 
system. Minutes and seconds represent the 
maximum number of minutes and seconds 
allotted for execution of the job step. 

Note s : 

• If the job step requires use of the 
system for 24 hours (1440 minutes) or 
longer, the programmer should specify. 
TIME=1440. Using this number 
suppresses timing. The number of 
seconds cannot exceed 59. 

• If the time limit is given in minutes 
only, the parentheses need not be 
coded; e.g., TIME=5. 

• If the time limit is given in seconds, 
the comma must be coded to indicate the 
absence of minutes; e.g., TIME=(,45). 

• When the job step uses a cataloged 
procedure, a time limit for a single 
procedure step can be set by qualifying 
the keyword TIME with the procedure 
step name; i.e., TIKE. procstep= 
(minutes, seconds) . This specification 
overrides the TIME parameter in the 
named procedure step if one is present. 
As many parameters of this form can be 
coded as there are steps in the 
cataloged procedure. 

• To set a time limit for an entire 
procedure, the TIME keyword is left 
unqualified. This specification 
overrides all TIME parameters in the 
procedure if any are present. 

• If this parameter is omitted, the 
standard job step time limit is 
assigned. 



Specifying Main St orage Requi rements for a 
Job St ep (REGION) 
(MVT only) 

The REGION parameter permits the 
programmer to specify the size of the main 
storage region to be allocated to the 
associated job step. The REGION parameter 
specifies: 

• The maximum amount of main storage to 
be allocated to the job. This amount 
must include the size of those 
components requxred oy the user s 
program that are not resident in main 
storage. 

• The amount of main storage to be 
allocated to the job, and the storage 
hierarchy or hierarchies in which the 
space is to be allocated. This request 
should be made only if main storage 
hierarchy support has been specified 
during system generation. If an IBM 
2361 Core Storage, Model 1 or 2, is 
present in the system, processor 
storage is referred to as hierarchy 
and 2361 Core Storage is referred to as 
hierarchy 1. If 2361 Core Storage is 
not present out main storage hierarchy 
support was specified in system 
generation, a two-part region is 
established in processor storage when a 
region is defined to exist in two 
hierarchies. The two parts are not 
necessarily contiguous. 

To specify a region size, code the 
keyword parameter in the operand field of 
the EXEC statement* 



REGION= (nnnnnxK [, nnnnnyK] ) 



2361 Model 2. Each value specified should 
be an even number. (If an odd number is 
specified, the system treats it as the next 
higher even number. ) 

If storage is requested only in 
hierarchy 1, a comma must be coded to 
indicate the absence of the first 
subpa rame ter , e.g., REGION= ( , 2 OK ) . If 
storage is requested only in hierarchy 0, 
or if hierarchy support is not present, the 
parentheses need not be coded, e.g., 
REGION=70K. 

If the REGION parameter is omitted or if 
a region size smaller than the default 
region size is requested, it is assumed 
that the default value is that established 
by the input reader procedure. 

Notes: 

• Region sizes for each job step can be 
coded by specifying the REGION 
parameter in the EXEC statement for 
each job step. However, if a REGION 
parameter is present in the JOB 
statement, it overrides REGION 
parameters in EXEC statements. 

• If main storage hierarchy support is 
not included but regions are requested 
in both hierarchies, the region sizes 
are combined and an attempt is made to 
allocate a single region from processor 
storage. If a region is requested 
entirely from hierarchy 1, an attempt 
is made to allocate the region from 
processor storage. 

• For information on storage requirements 
to be considered when specifying a 
region size, see the publication IBM OS 
S torage Estimates . 



To request the maximum amount of main 
storage required by the job, replace the 
term "nnnnnx" with the maximum number of 
contiguous 1024-byte areas allocated to the 
job step, e.g., REGION=52K. This number 
can range from 1 to 5 digits but must not 
exceed 16383. 

To request a region size and the 
hierarchy desired, the term "nnnnnx" is 
replaced with the number of contiguous 
1024-byte areas to be allocated to the jod 
in hierarchy 0; the term "nnnnny" is 
replaced with the number of contiguous 
1024-byte areas to be allocated in 
hierarchy 1, e.g., REGION=(60K, 200K) . When 
only processor storage is used to include 
hierarchies and 1, the combined values of 
nnnnnx and nnnnny cannot exceed 16383. If 
2361 Core Storage is present, nnnnnx cannot 
exceed 16383 and, for a 2361 Model 1, 
nnnnny cannot exceed 1024, or 2048 for a 



Specifying Additional Main S torage f or a 
Job Step (ROLL) 
(MVT only) 

To allocate additional main storage to a 
job step whose own region does not contain 
any more available space, code the keyword 
parameter in the operand field of the EXEC 
statement. 



ROLL=(x, y) 



In order to allocate this additional space 
to a job step, another job step may have to 
be rolled out, i.e., temporarily 
transferred to secondary storage. When x 
is replaced with YES, the job step can be 
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rolled out; when x is replaced with NO, the 
job step cannot be rolled out. When y is 
replaced with YES, the job step can cause 
rollout; when y is replaced with NO, the 
job step cannot cause rollout. (If 
additional main storage is required for the 
job step, YES must be specified for y. ) If 
this parameter is omitted, ROLL=(YES, NO) is 
assumed. 

Notes : 



ability to be rolled out and to cause 
rollout of other job steps, the ROLL 
parameter can be coded without a 
procedure stepname. This specification 
overrides all ROLL parameters in the 
procedure, if any are present. 



DD STATEMENT 



• If the ROLL parameter is specified in 
the JOB statement, the ROLL parameter 
in the EXEC statements is ignored. 

• When a job step uses a cataloged 
procedure, it can be indicated whether 
or not a single procedure step has the 
ability to be rolled out and to cause 
rollout of another job step. To 
indicate this, the procedure stepname, 
i.e., ROLL.procstepname, is included as 
part of the ROLL parameter. This 
specification overrides the ROLL 
parameter in the named procedure step, 
if one is present. As many parameters 
of this form can be coded as there are 
steps in the cataloged procedure. 

• To indicate whether or not all of the 
steps of a cataloged procedure have the 



The data definition (DD) statement 
identifies each data set that is to be used 
in a job step, and it furnishes information 
about the data set. The DD statement 
specifies input/output facilities required 
for using the data set; it also establishes 
a logical relationship between the data set 
and input/output references in the program 
named in the EXEC statement for the job 
step. 

Figure 7 is a general format of the DD 
statement. 

Parameters used most frequently for 
COBOL programs are discussed in detail. 
The other parameters (e.g., SEP and AFF) 
are mentioned briefly. For further 
information, see the publication IBM OS Job 
Control Languag e Reference . 
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Name 



■T T* 

| Operation | 



Operand 



iddname 

I// < > I 

| fprocstep. ddname \ \ 

i :• 1 ±. 



DD 



(see below and next page) 



Operand 2 



Positional Parameters 



* 

ri Am* 

DUMMY 



Keyword P a rameters ** 5 
[DDNAME=ddname] 



Idsname/ 
/dsn J 



dsname 

dsname( element) 

* . ddname 

* . stepname. ddname 

* . stepname. procstep. ddname 

££name 

6 &name ( element ) 



[QNAME=processname] 
DCB=( 



dsname 

♦.ddname 
*. stepname. ddname 
*. stepname. procstep. ddname 



[ , subparameter-list] ) 



ist) 7 ] 



SEP=(subparameter 1 
AFF=ddname 

Positi onal Subparamete rs Keyword Subparameters 

UNIT=(name[ # [n/P] [, DEFER] ] [ # SEP= (list of up to 8 ddnames)]) 8 
UNIT= ( AFF=ddname ) 

Positional Subparame t ers 



Jtrk 

SPACE=( jcYL 

/ average-record-length 



, (primary-quantity [, secondary-quantity] , 



[directory- or index-quantity] ) [ # RLSE] 



, MXLG 

, ALX 

( CONTIG 



[, ROUND]) 



SPACE=(ABSTR f (quantity, beginning-address [, directory- or index-quantity])) 

$ CYL \ 

l, \ i i ({jriiuciry— quantity [, secondary— quantity] ) ) 

/average-record- length) 



SPLIT— (n. 



,TRK 
SUBALLOC=( JCYL 



laverage-record-lengtm 



, (primary-quantity [ , secondary-quantity] 



\ ddname / 

[, directory-quantity] ) , {stepname. ddname } ) 

/stepname. procstep. ddname) 



Figure 7. The DD Statement (Part 1 of 2) 
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I Operand 2 (cont. ) 
j. 



'unT.ITMT?'. 



Positio nal Subpar ameters 



VOLUME 1 



i = ( [PRIVATE], [RETAIN] , [volume sequence number] , [volume count]) 



Keyword Subparameters 



, SER= (volume- serial-number [volume-serial-number] 9 . . . > 

Idsname j 

)* . ddname ( 



,REF= 



isname 
ddname 

stepname. ddname ( 
stepname.procstep. ddname \ 



(NL 
LABEL=( [data-set-sequence-number], /SL 

iNSL 
'sul 



DISP=( 



SYSOUT=classname 

SYSOUT= ( x [ , program- name] [ , form-no. ] ) 



[: 



, EXPDT=yyddd 1 
RETPD=xxxx J 



[PASSWORD] ) 



new" 




[delete 




, DELETE 


OLD 




,keep 




,KEEP 


SHR 




,PASS 




, CATLG 


MOD_ 




, CATLG 
, UNCATLG 




, UNCATLG 



*-The name field must be blank when concatenating data sets. 

2 A11 parameters are optional to allow a programmer flexibility in the use of the DD 

statement; however, a DD statement with a blank operand field is meaningless. 
3 If the positional parameter is specified, keyword parameters other than DCB cannot be 

specified. 
**If subparameter-list consists of only one subparameter and no leading comma 

(indicating the omission of a positional subparameter) is required, the delimiting 

parentheses may be omitted. 
5 If su£>parameter-list is omitted, the entire parameter must be omitted. 
6 See "User-Defined Files" for the applicable subparameters. 
7 See the publication IBM OS Job Control Language Reference. 
a If only name is specified, the delimiting parentheses may be omitted. 
9 If only one volume-serial-number is specified, the delimiting parentheses may be 

omitted. 
3 -°The SEP and AFF parameters should not be confused with the SEP and AFF subparameters 

of the UNIT parameter. 
13 -The value specified may contain special characters if the value is enclosed in 

apostrophes. If the only special character used is the hyphen, the value need not be 

enclosed in apostrophes. If DSNAME is a qualified name, it may contain periods 

without being enclosed in apostrophes. 
ia The unit address may contain a slash, and the unit type number may contain a nyphen, 

without being enclosed in apostrophes, e.g., UNIT=293/5, UNIT=2400-2. 
13 The QNAME= parameter is used in COBOL teleprocessing and must be the name of a ICAM 

destination queue. 

L 

Figure 7. The DD Statement (Part 2 of 2) 
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Name Field 

ddname (Identifying the DD Statement) 
is used: 

• To identify data sets defined by 
this DD statement to the compiler or 
linkage editor (see "Compiler Data 
Set Reguirements" and "Linkage 
Editor Data Set Reguirements"). 

• To relate the data sets defined in 
this DD statement to a file 
described in a COBOL source program 
(see "User-Defined Files"). 

• To identify this DD statement to 
other control statements in the 
input stream. 

procstep. ddname 

is used to alter or add DD statements 
in cataloged procedures. The step in 
the cataloged procedure is identified 
by procstep. The ddname identifies 
either one of the following: 

• A DD statement in the cataloged 
procedure that is to be modified by 
the DD statement in the input 
stream. 

• A. DD statement that is to be added 
to the DD statement in the procedure 
step. 



Oper and Field 

* (Defining Data in an Input Stream) 
indicates that data immediately 
follows this DD statement in the input 
stream. This parameter is used to 
specify a source deck or data in the 
input stream. If the EXEC statement 
specifies execution of a program, only 
one data set may be placed in the 
input stream. The end of the data set 
must be indicated by a delimiter 
statement. The data cannot contain // 
or /* in the first two characters of 
any record. The DD * statement must 
be the last DD statement of the job 
step. In MVT, for a step with a 
single input stream data set, DD * and 
a /* statement are not reguired. The 
system will supply both if missing. 
The default DDNAME will be SYSIN. " 

DATA (Defining Data in an Input Stream) 

also indicates a source deck or data 
in the input stream. If the EXEC 
statement specifies execution of a 
program, only one data set may be 
placed in the input stream. The end 
of the data set must be indicated by a 
delimeter statement. The data cannot 
contain /* in the first two characters 
of any record. The DD DATA statement 



must be the last DD statement of the 
job step. // may appear in the first 
and second positions in the record, 
for example, when the data consists of 
control statements of a procedure that 
is to be cataloged. 



DUMMY (Bypassing Input/Output Operations on 
the Data Set) 

allows the user's processing program 
to operate without performing 
input/output operations on the data 
set. The DUMMY parameter is valid 
only for seguential data sets to which 
reference is made by the basic 
seguential or gueued seguential file 
processing technigues. If the DUMMY 
parameter is specified, a read reguest 
results in an end of data set exit. A 
write reguest is recognized, but no 
data is transmitted. No device 
allocation, external storage 
allocation, or cataloging takes place 
for dummy data sets. 



In multiprogramming environments, data 
in the input stream is temporarily 
transferred to a direct-access device for 
later high-speed retrieval. Normally, the 
reader procedure assigns a blocking factor 
for the data when it is placed on the 
direct-access device. The programmer may 
assign his own values through use of the 
BLKSIZE parameter of the DCB parameter. He 
may also indicate the number of buffers to 
be assigned to transmitting the data, 
through use of the BUFNO parameter. For 
example, he may assign the following: 



DCB=(BLKSIZE=800,BUFNO=2) 



If the programmer omits these parameters or 
assigns values greater than the capacity of 
the input reader, it is assumed that the 
established default values for the reader 
are in effect. 



DDNAME Parameter (Postponing the Definition 

of a Dat a S et ) 

defines a pseudo data set that will 
assume the characteristics of a real 
data set if a subseguent DD statement 
of the step is labeled with the 
specified ddname. When the DDNAME 
parameter is specified, it must be the 
first parameter in the operand. All 
other parameters are ignored and 
should be omitted when the DDNAME 
parameter appears (see "Using the 
Cataloged Procedures " ) . 
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DDN AME Subparam e ter 

ddname 

names a DD statement that, if 
present, supplies the attributes 
of the data set. If it is not 
present, the statement is 
ignored. 



DSNAME Parameter (Iden tifying the Data Set) 
allows the programmer to specify the 
name of the data set to be created or 
to refer to a previously created data 
set. Various types of names can be 
specified (see "Using the DD 
Statement" for a discussion of the 
various names) as follows: 

• Ful l y qual i fied names: For data 
sets to be retrieved from or stored 
in the system catalog. 

• Generatio n data gr oup name s: For an 
entire generation data group, or any 
single generation thereof. 

• Simple names: For data sets that 
are not cataloged. 

• Reference n ames: For data sets 
whose names are given in the DSNAME 
parameter of another DD statement in 
the same job. 

• Temporary names : For temporary data 
sets that are to be named for the 
duration of one job only. 

If the DSNAME parameter is omitted, 
the operating system assigns a unique 
name to the data set. (This parameter 
should be supplied for all except 
temporary data sets to allow future 
referencing of the data set. ) DSNAME 
may be coded DSN. 

D SNAME S ubparam e ters 

dsname 

specifies the fully qualified 
name of a data set. This is the 
name under which the data set can 
be cataloged or otherwise 
identified on the volume. 

dsname (element) 

specifies a particular generation of a 
generated data group, a member of a 
partitioned data set, or an area of an 
indexed data set. To indicate a 
generation of a generated data group, 
the element is a zero or a signed 
integer. To indicate a member of a 
partitioned data set, the element is a 
name. To indicate an area of an 
indexed data set, the element is 
PRIME, OVFLOW, or INDEX (see "Using 
the DD Statement" for information 



about generation data groups and 
examples of partitioned data sets). 

*. ddname 

indicates that the DSNAME parameter 
(only) is to be copied from a 
preceding DD statement in the current- 
job step. 

* . stepname. ddname 

indicates that the DSNAME parameter 
(only) is to be copied from the DD 
statement, ddname, that occurred in a 
previous step, stepname, in the 
current job. If this form of the 
subparameter appears in a DD statement 
of a cataloged procedure, stepname 
refers to a previous step of the 
procedure, or, if no such step is 
found, to a previous step of the 
current job. 

* . stepname. procstep. ddname 

indicates that the DSNAME parameter 
(only) is to be copied from a DD 
statement in a cataloged procedure. 
The EXEC statement that called for 
execution of the procedure, as well as 
the step and DD statement of the 
procedure, must £>e identified. 

SSname 

allows the programmer to supply a 
temporary name for a data set that is 
to be deleted at the end of the job. 
The operating system substitutes a 
unique symbol for this subparameter. 
The programmer can use the temporary 
name in other steps to refer to the 
data set. The same symbol is 
substituted for each recurrence of 
this name within the job. Upon 
completion of the job, the name is 
dissociated from the data set. The 
same temporary name can be used in 
other jobs without ambiguity. 

& &name ( element ) 

allows the programmer to supply a name 
for a member of a temporary 
partitioned data set that will be 
deleted at the end of the step. 



QNAME Paramet er (Defining the Data to oe 

Accessed by TCAM) 

specifies the name of a TPROCESS macro 
that defines a destination queue for 
messages that are to be processed by 
an application program and creates a 
process entry for the queue in the 
Terminal Table (see the section 
"Defining Terminal and Line Control 
Areas" in the chapter entitled "Using 
the Teleprocessing Feature"). 

Note : The DCB parameter is the only 
parameter that can be coded on a DD 



50 



statement with the QNAME parameter. 
The only operands that may be 
specified as subparameters are 
BLKSIZE, BUFL, LRECL, OPTCD, and 
RECFM. 



If the UNIT parameter is not specified 
in the current DD statement, there are 
several ways in which the unit 
information may be inferred by the 
system: 



DCB Parameter (De scribing 
the Data Set) 



the Attributes of 



allows the programmer to specify at 
execution time, rather than at 
compilation time, information for 
completing the data control block 
associated with the data set (see 
"Execution Time Data Set Requirements" 
and "Additional File Processing 
Information" for further information 
about the data control block and DCB 
subparameters) . 

The first subparameter of this 
parameter may be used to copy DCB 
attributes from the data set label of 
a cataloged data set or from a 
preceding DD statement (see the 
publication IBM OS Supervisor an d Data 
Management Macro Instructions for 
detailed information about the DCB 
subparameter) . 



SEP an d AFF Param et ers (Optimizin g Channel 

Usa ge) 

allow the programmer to optimize the 
use of channels among groups of data 
sets. SEP indicates channel 
separation and AFF indicates channel 
affinity. 

If neither parameter is supplied, any 
available channel, consistent with the 
UNIT parameter requirement, is 
assigned. The affinity parameter 
groups two or more data sets so that 
they can be separated from another 
data set requesting channel 
separation. For indexed sequential 
data sets these parameters are written 
in the same way as those for any data 
set. They can be used in succeeding 
DD statements to refer to the first DD 
statement defining an indexed 
sequential data set. However, the 
second and third DD statements cannot 
request separation from or affinity to 
one another because they are unnamed. 
Thus, to establish channel separation 
and affinity for all of the areas, the 
name subparameter of the UNIT 
parameter must be used to request 
specific devices on specific channels. 



U NIT Parame te r (Re q uesting a Unit ) 

specifies the quantity and types of 
input/output devices to be allocated 
for use by the data set. 



• If the current data set has already 
been created and it is either being 
passed to the current step, or if it 
has been cataloged, any unit name 
specified in this DD statement is 
iqnored. 



If the REF subparameter of the 
VOLUME parameter is specified, the 
current data set is given affinity 
with the data set referred to; that 
data set's defining DD statement 
provides the unit information. 



• If the current data set is to 

operate in the split cylinder mode 
with a previously defined data set, 
it will reside on the unit specified 
in the DD statement for the previous 
data set. 



• If the current data set is to use 
space suballocated from that 
assigned to a previously defined 
data set, it will reside on the same 
unit as the data set from which the 
space is obtained. 

• If the current data set is assigned 
to the standard output class (SYSOUT 
is specified) , it is written on the 
unit specified by the operator for 
class A. 

If the current data set is in the input 
stream (defined by a DD * or DD DATA 
statement) , the DD statement defining the 
data set should not contain a UNIT 
parameter. 

If this parameter specifies a mass 
storage device for a data set being 
created, it is also necessary to reserve 
the space the data set will occupy, using 
another parameter of the DD statement. 
Depending on the way in which the space 
will be used, the SPACE, SPLIT, or SUBALLOC 
parameter can be specified. These 
parameters are discussed under individual 
headings. 

If the UNIT parameter specifies a tape 
device, no SPACE, SPLIT, or SUBALLOC 
parameters are required. 

The UNIT parameter must be specified if 
VOLUME=SER is specified in the DD 
statement. 
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UNIT Subparameters : 

name 

specifies the name of an input/output 
device, a single cell within a data 
cell drive, a device class name, or 
any meaningful combination of 
input/output devices specified by an 
installation. (Mass storage devices 
and magnetic tape devices can be 
combined. No other device type 
combination is allowed. ) Names and 
device classes are defined at system 
generation time. The device class 
names that are required for IBM 
cataloged procedures and are normally 
used by most installations are shown 
in Figure 8. These names can be 
specified by the installation at 
system generation time. 



The block size specified in the source 
program (in the BLOCK CONTAINS clause 
or in the record description) must not 
exceed the maximum block size 
permitted for the device. For 
example, the maximum block size for 
the IBM 2311 is 3625 characters, and 
the maximum block size for the IBM 
2400 series is 32, 760 characters. 



Note ; When device-independence is 
specified by use of UT as the device 
class in the ASSIGN statement in the 
Environment Division, the device 
chosen by the system will be dependent 
on the DD statement. Therefore, if 
the user's installation has both an 
IBM 2311 and an IBM 2302 that may be 
used as utility devices, the user 
should write 

BLOCK CONTAINS 36 25 CHARACTERS 

(or any number smaller than 3625) to 
ensure that the block can be contained 
on one track. 



specifies the number of devices to be 
allocated to the data set. If this 
parameter is omitted, 1 is assumed. 



specifies parallel mount. 



DEFER 



indicates deferred mounting. Deferred 
mounting cannot be specified for a new 
output data set on a mass storage 
device or for an indexed data set. 



SEP=(list of up to eight ddnames) 
specifies unit separation. 



AFF=ddname 

specifies unit affinity. 



r t t 1 

j Class Name (Class Functions | Device Type | 

JSYSSQ | writing I mass storage j 
j j reading | magnetic tape j 



h 



4- 



SYSDA 



-+ "I 

J mass storage | 



Figure 8. 



| writing 

| reading | | 

.x J. J 

Device Class Names Required for 
IBM-Supplied Cataloged 
Procedures 



SPACF Parameter (Allocating Mass Storage 

Spjice)_ 

specifies space to be allocated in a 
mass storage volume. Although SPACE 
has no meaning for tape volumes, if a 
data set is assigned to a device class 
that contains both mass storage 
devices and tape devices, SPACE should 
be specified. 

Two forms of the SPACE parameter may 
be used, with or without absolute 
track address (ABSTR) . The ABSTR 
parameter requests that allocation 
begin at a specific address. 



SPACE Subparameters; 

( ABSTR 

>TRK 

\CYL 

(average- record- length , 

specifies the unit of measurement in 
which storage is to be assigned. The 
units may be tracks (ABSTR or TRK) , 
cylinders (CYL), or records 
(average-record-length, expressed as a 
decimal number). In addition, the 
ABSTR subparameter indicates that the 
allocated space is to begin at a 
specific track address. If the 
specified tracks are already allocated 
to another data set, they will not be 
reallocated to this data set. 

Note: For indexed data sets, only the 
CYL or ABSTR subparameter is 
permitted. When an indexed data set 
is defined by more than one DD 
statement, all must specify either CYL 
or ABSTR; if some statements contain 
CYL and others ABSTR, the job will be 
abnormally terminated. 



( primary-quantity C , secondary-guanti ty ] 
[, directory- or index-quantity]) 

specifies the amount of space to be 
allocated for the data set. The 
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primary quantity indicates the number 
of records, tracks, or cylinders to be 
allocated when the job step begins. 
For indexed data sets, this 
subparameter specifies the number of 
cylinders for the prime, overflow, or 
index area (see "Execution Time Data 
Set Requirements"). The secondary 
quantity indicates how much additional 
space is to be allocated each time 
previously allocated space is 
exhausted. This subparameter must not 
be specified when defining an indexed 
data set. If a secondary quantity is 
specified for a sequential data set, 
the program may receive control when 
additional space cannot allocated to 
write a record. The directory 
quantity is used when initially 
creating a partitioned data set (PDS), 
and it specifies the number of 
256-byte records to be reserved for 
the directory of the PDS. It can also 
specify the number of cylinders to be 
allocated for an index area embedded 
within the prime area when a new 
indexed data set is being defined (see 
the publication IBM OS Job C ontrol 
Language Ref e rence > . 



Note : The directory contains the name 
and the relative position, within the 
data set, for each member of a 
partitioned data set. The name 
requires eight bytes, the location 
four bytes. Up to 62 additional bytes 
can be used for additional 
information. For a directory of a 
partitioned data set that contains 
load modules, the minimum directory 
requirement for each member is 34 
bytes. 



RLSE 

indicates that all unused external 
storage assigned to this data set is 
to be released when processing of the 
data set is completed. 

MXIS 

ALX 

CONTIG 

qualifies the request for the space to 
be allocated to the data set. MXIG 
requests the largest single block of 
storage that is greater than or equal 
to the space requested in the primary 
quantity. ALX requests the allocation 
of additional tracks in the volume. 
The operating system will allocate 
tracks in up to five blocks of 
storage, each block equal to or 
greater than the primary quantity. 
CONTIG requests that the space 
indicated in the primary quantity be 
contiguous. 



If this subparameter is not 
specified, or if any option cannot be 
fulfilled, the operating system 
attempts to assign contiguous space. 
If there is not enough contiguous 
space, up to five noncontiguous areas 
are allocated. 



ROUND 



indicates that allocation of space for 
the specified number of records is to 
begin and end on a cylinder boundary. 
It can be used only when average 
record length is specified as the 
first subparameter. 



quantity 

specifies the number of tracks to be 
allocated. For an indexed data set, 
this quantity must be equivalent to an 
integral number of cylinders; it 
specifies the space for the prime, 
overflow, or index area (see 
"Execution Time Data Set 
Requirements" ) . 



beginning address 

specifies the relative number of the 
track desired, where the first track 
of a volume is defined as 0. (Track 
cannot be requested. ) The number is 
automatically converted to an address 
based on the particular device 
assigned. For an indexed data set 
this number must indicate the 
beginning of a cylinder. 

directory quantity 

defines the number of 256-byte records 
to be allocated for the directory of a 
new partitioned data set. It also 
specifies the number of tracks to be 
allocated for an index area embedded 
within the prime area when a new 
indexed data set is being defined. In 
the latter case, the number of tracks 
must be equivalent to an integral 
number of cylinders (see the 
publication IBM OS Job Contr ol 
Langua ge Reference ) . 



SPLIT Parameter (A ll oc at ing Mass Storage 

Space) 

is specified when other data sets in 
the job step require space in the same 
mass storage volume, and the user 
wishes to minimize access-arm movement 
by sharing cylinders with the other 
data sets. The device is then said to 
be operating in a split cylinder mode. 
In this mode, two or more data sets 
are stored so that portions of each 
occupy tracks within every allocated 
cylinder. 
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Note : SPLIT should not be used when 
one of the data sets is an indexed 
data set. 



further suballocated. The SUBALLOC 
parameter should not be used to obtain 
space for an indexed data set. 



SPLIT Sub paramete rs: 

n 

indicates the number of tracks per 
cylinder to be used for this data set 
if CYL is specified. If the average 
record length is specified # n is the 
percentage of the tracks per cylinder 
to be used for this data set. 

CYL \ 

average- record-length ) 

indicates the units in which the space 
reguirements are expressed in the next 
subparameter. The units may be 
cylinders (CYL) or physical records 
(in which case the average record 
length in bytes is specified as a 
decimal number not exceeding 65,535). 
If the average record length is given, 
and the data set is defined to have a 
key, the key length must be given in 
the DCB parameter of this DD 
statement. 



primary-quantity 

defines the number of cylinders or 
space for records to be allocated to 
the entire group of data sets. 



secondary- quantity 

defines the number of cylinders or 
space for records to be allocated each 
time the space allocated to any of the 
data sets in the group has been 
exhausted and more data is to be 
written. This quantity will not be 
split. 



A group of data sets that share 
cylinders in the same device is 
defined by a sequence of DD 
statements. The first statement in 
the sequence must specify all 
parameters except secondary quantity, 
which is optional. Each of the 
statements that follow the first 
statement must specify only n, the 
amount of space required. 



S UBALLOC Paramete r (Allocating Ma ss St orage 

S pace) 

permits space to be obtained from 
another data set for which contiguous 
space was previously allocated. This 
enables data sets to be stored in a 
single volume. Space obtained through 
suballocation is removed from the 
original data set, and may not be 



Except for the subparameters 
described below, the subparameters in 
the SUBALLOC parameter have the same 
meaning as those described in the 
SPACE parameter. 



SUBALLOC Sub parameters ; 

ddname 

indicates that space is to be 
suballocated from the data set defined 
by the DD statement, ddname, that 
appears in the current step. 

stepname. ddname 

indicates that space is to be 
suballocated from the data set defined 
by the DD statement, ddname, occurring 
in a previous step, stepname. If this 
form of the subparameter appears in a 
DD statement in a cataloged procedure, 
stepname refers to a previous step of 
the procedure, or if no such step is 
found, to a previous step of the 
current job. 



stepname. procstep. ddname 

indicates that space is to be 
suballocated from a data set defined 
in a cataloged procedure. The first 
term identifies the step that called 
for execution of the procedure, the 
second identifies the procedure step, 
and the third identifies the DD 
statement that originally requested 
space. 



VOLUME (VO L) Parameter (Specifying Volume 

Informa tion) 

specifies information about the 
volume(s) on which an input data set 
resides, or on which an output data 
set will reside. A volume can be a 
tape reel, or a mass storage device. 
Volumes can be used most efficiently 
if the programmer is familiar with the 
states a volume can assume. Volume 
states involve two criteria: the type 
of data set the programmer is defining 
and the manner in which the programmer 
requests a volume. 

Data sets can be classified as one 
of two types, temporary or 
nontemporary . A temporary data set 
exists only for the duration of the 
step that creates it. A nontemporary 
data set can exist after the job is 
completed. The programmer indicates 
that a data set is temporary by 
coding: 
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DSNAME=S&name 



• No DSNAME parameter 

• DISP=< NEW, DELETE), either explicitly 
or implied, e.g., DISP=(, DELETE) 

• DSNAME=ref erence, referring to a DD 
statement that defines a temporary 
data set. 

All other data sets are considered 
nontemporary, if the programmer 
attempts to keep or catalog a passed 
data set that was declared temporary, 
the system changes the disposition to 
PASS unless DEFER was specified in 
theUNIT parameter. Such a data set is 
deleted at the end of the job. 

The manner in which the programmer 
requests a volume can be considered 
specific or nons pecific . A specific 
reference is implied whenever a volume 
with a specific serial number is 
requested. Any one of the following 
conditions denotes a specific volume 
reference: 

• The data set is cataloged or passed 
from an earlier job step. 

• VOLUME=SER is coded in the DD 
statement. 

• VOLUME=REF is coded in the DD 
statement, referring to an earlier 
specific volume reference. 

All other types of volume references 
are nonspecific. (Nonspecific 
references can be made only for new 
data sets, in which case the system 
assigns a suitable volume. ) 

The state of a volume determines 
when the volume will be demounted and 
what kinds of data sets can be 
assigned to it. 

Mass Storage Volumes : Mass storage 
volumes differ from tape volumes in 
that they can be shared by two or more 
data sets processed concurrently by 
more than one job* Because of this 
difference, mass storage volumes can 
assume different volume states than 
tape volumes. The volume state is 
determined by one characteristic from 
each of the following groups: 



Mount 

Characte ristics 

Permanently 

Resident 
Reserved 
Removable 



Allocation 

Character istics 

Public 

Private 
Storage 



Permanently resident volumes are 
always mounted. The permanently 
resident characteristic applies 
automatically to: 

• All physically permanent volumes, 
such as 2301 Drum Storage. 

• The volume from which the system is 
loaded (the IPL volume). 

• The volume containing the system 
data sets SYS1. LINKLIB, 
SYS1.PROCLIB, and SYS1. SYSJOBQE. 

• Other volumes can be designated as 
permanently resident in a special 
member of SYS1.PROCLIB named 
PRESRES. 

Permanently resident volumes are 
always public. The reserved 
characteristic applies to volumes that 
remain mounted until the operator 
issues an UNLOAD command. They are 
reserved by a MOUNT command referring 
to the unit on which they are mounted 
or by a PRESRES entry. The removable 
characteristic applies to all volumes 
that are neither permanently resident 
nor reserved. Removable volumes do 
not have an allocation characteristic 
when they are not mounted. A reserved 
volume becomes removable after an 
UNLOAD command is issued for the unit 
on which it resides. 

The allocation characteristics, 
public, private, and storage, indicate 
the availability status of a volume 
for assignment by the system to 
temporary data sets, and, if the 
volume is removable, when it is to be 
demounted. A public volume is used 
primarily for temporary data sets and, 
if it is permanently resident, for 
frequently used data sets. It must be 
requested by a specific volume 
reference if a data set is to be kept 
or cataloged on it. If a public 
volume is removable, it is demounted 
only when its unit is required by 
another volume. The programmer can 
change a public volume to private 
status by specifying VOLUME=PRIVATE. 
A private volume must be requested by 
a specific volume reference. A new 
data set can be assigned to a private 
volume by specifying VOLUME=PRIVATE. 
If the volume is reserved, it remains 
mounted until the operator issues an 
UNLOAD command for the unit on which 
it resides. If it is removable, it 
will be demounted after it is used, 
unless the programmer specifically 
requested that it be retained 
(VOLUME= r RETAIN) or passed 
(DISP=, PASS) . Once a removable volume 
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has been made private, it will 
ultimately be demounted. To use it as 
a public volume, it must be remounted. 
A storage volume is used as an 
extension of main storage, to keep or 
catalog nontemporary data sets having 
nonspecific volume requests. The 
programmer can assign the PRIVATE 
option to storage volumes. 



Table 3 shows how mass storage 
volumes are assigned their mount and 
allocation characteristics. 



• It is requested for allocation to a 
nontemporary data set. 

• The VOLUME parameter is coded with 
the PRIVATE option. 

A removable- private volume is 
demounted after its last use in the 
job step, unless the programmer 
requests that it be retained. 

All other tape volumes are assigned 
the removab l e -scratch state. The tape 
volumes remain mounted until their 
unit is required by another volume. 



Table 3. Mass Storage Volume States 
r t 
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Ma gne t ic Tap e Volumes ; The volume 
state of a reel of magnetic tape is 
also determined by a combination of 
mount and allocation characteristics 



Mount 

Characterist ics 
Reserved 
Removable 



Allocation 
Charact eristics 
Private 
Scratch 



The reserved-scratch combination is 
not a valid vol ume state. Reserved 
tape volumes assume their state when 
the operator issues a MOUNT command 
for the unit on which they reside. 
They remain mounted until the operator 
issues a corresponding UNLOAD command. 
Reserved tapes must be requested by a 
specific volume reference. 

A removabl e tape volume is assigned 
the pr ivate characteristic when one of 
the following occurs: 

• It is requested with a specific 
volume reference. 



Vo lume Parameter Facilities ; The 
facilities of the VOLUME parameter 
allow the programmer to: 

• Request private volumes (PRIVATE) 

• Request that private volumes remain 
mounted until the end of the job 
(RETAIN) 

• Select volumes when the data set 
resides on more than one volume 
(volume-sequence-number) 

• Request more than one nonspecific 
volume (volume-count) 

• Identify specific volumes (SER and 
REF) 

These facilities are all optional. 
The programmer can omit the VOLUME 
parameter when defining a new data 
set, in which case the system assigns 
a suitable public or scratch volume. 

VOLUME Subparameters: 

PRIVATE 

indicates that the volume on which 
space is being allocated to the data 
set is to be made private. If the 
PRIVATE, SER, and REF subparameters 
are omitted for a new output data set, 
the system assigns the data set to any 
suitable public or scratch volume that 
is available. 

RETAIN 

indicates that this volume is to 
remain mounted after the job step is 
completed. Volumes are retained so 
that data may be transmitted to or 
from the data set, or so that other 
data sets may reside in the volume. 
If the data set requires more than one 
volume, only the last volume is 
retained; the other volumes are 
previously dismounted. Another job 
step indicates when to dismount the 
volume by omitting RETAIN. If each 
job step issues a RETAIN for the 
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volume, the retained status lapses 
when execution of the job is 
completed. 

volume-sequence-number 

is a 1- to 4-digit number that 
specifies the sequence number of the 
first volume of the data set that is 
read or written. The volume sequence 
number is meaningful only if the data 
set is cataloged and earlier volumes 
are omitted. 

volume-count 

specifies the number of volumes 
required by the data set. Unless the 
SER or REF subparameter is used this 
subparameter is required for every 
multivolume output data set. 



SER 



REF 



specifies one or more serial numbers 
for the volumes required by the data 
sets. A volume serial number consists 
of one to six alphanumeric characters. 
If it contains fewer than six 
characters, the serial number is left 
justified and padded with blanks. If 
SER is not specified and DISF is not 
specified as NEW, the data set is 
assumed to be cataloged, and serial 
numbers are retrieved from the 
catalog. A volume serial number is 
not required for new output data sets. 
Two volumes should not have the same 
serial number. When the SER parameter 
is included, the volume is treated as 
PRIVATE commencing with allocation for 
the current job step. If this 
subparameter is specified, the UNIT 
parameter must also be specified. 



indicates that the data set is to 
occupy the same volume (s) as the data 
set identified by dsname *.ddname, 
♦.stepname. ddname, or *. stepname. 



procstep. ddname. Table 4 shows the 
data set references. 

When the data set resides in a tape 
volume and REF is specified, the data 
set is placed in the same volume, 
immediately behind the data set 
referred to by this subparameter. 
When the REF subparameter is used, the 
UNIT and LABEL parameters, if 
supplied, are ignored. 

If SER or REF is not specified, the 
control program will allocate any 
nonprivate volume that is available. 

LABEL Parameter (Describing Data Set Label) 
specifies information about the label 
or labels associated with the data 
set. If a data set is passed from a 
previous job step, label information 
is retained from the DD statement that 
specified DISP= (, PASS) . A LABEL 
parameter, if specified in the DD 
statement receiving the passed data 
set, is ignored. If the LABEL 
parameter is omitted and the data set 
is not being passed, standard labeling 
is assumed. The operating system 
verifies mounting when the label 
parameter specifies standard labels 
(SL) or standard and user labels 
(SUL). Nonstandard labels can be 
specified only when installation- 
written routines to write and process 
nonstandard labels have been 
incorporated into the operating system 
(see "User Label Processing" and tne 
publication IBM. Syst em/360 Operating 
System: Systems Programmer 1 s_Guide 
for information about writing these 
routines) . 

L^E^_S u^a^ame ter s : 

data-set-sequence-number 

is a 4-digit number that identifies 
the relative location of the data set 



Table 4. Data Set References 
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| REF=*. stepname. procstep. ddname | A data set indicated by DD statement ddname in the 

| | cataloged procedure step procstep called in the job step 

j j stepname (see "Using the Cataloged Procedures") 

l j. 
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with respect to the first data set in 
a tape volume. (For example, if there 
are three data sets in a magnetic tape 
volume, the third data set is 
identified by data set sequence number 
0003.) If the data set sequence 
number is not specified, the operating 
system assumes that it is 0001. (This 
option should not be confused with the 
volume sequence number, which 
represents a particular volume for a 
data set. ) 

i NL ) 
JSL ( 

insl( 
[sul) 

specifies the kind of label used for 
the data set. NL indicates no labels. 
SL indicates standard labels. NSL 
indicates nonstandard label. SUL 
indicates standard and user labels. 

EXPDT=yyddd 

RETPD=xxxx 

specifies how long the data set shall 
exist. The expiration date, 
EXPDT=yyddd, indicates the year (yy> 
and the day (ddd) that the data set 
can be deleted. The period of 
retention, RETPD=xxxx, indicates the 
period of time, in days, that the data 
set is to be retained. If neither is 
specified, the retention period is 
assumed to be zero. 

PASSWORD 

indicates that the data set is to be 
made accessible only when the correct 
password is issued by the operator. 
The operating system assigns security 
protection to the data set. In order 
to retrieve the data set, the operator 
must issue the password on the 
console. 

DISP Parameter (Specifyin g Da ta Set Status 

and_ Disposition) 

describes the status of a data set and 
indicates what is to be done with it 
after its last use, or at the end of 
the job. The job scheduler executes 
the requested disposition functions at 
the completion of the associated job 
step. If the step is not executed 
because of an error found by the 
system before trying to initiate the 
step (e.g., an error in a job control 
language statement), the remaining 
statements are read and interpreted; 
however, none of the succeeding steps 
are executed, and the requested 
dispositions are not performed. This 
parameter can be omitted for data sets 
created and deleted during a single 
job step. Additional information 
about the relationship between the 
DISP parameter and the volume table of 



contents is contained in "Additional 
File Processing Information. " 

DI SP_S ubpar ame ter s : 

NEW 

indicates that the data set is being 
generated in this step. If the status 
is omitted, the NEW subparameter is 
assumed. 



OLD 



SHR 



indicates that the data set specified 
in the DSNAME parameter already 
exists. 



has meaning only in a multiprogramming 
environment for existing data sets 
that reside on mass storage volumes. 
This subparameter indicates that the 
data set is part of a job in which 
operations do not prevent simultaneous 
use of the data set by another job. 
For a data set that is to be shared, 
the DD statement DISP parameter should 
be specified as DISP=SHR for every 
reference to the data set in a job. 
Unless this is done, the data set 
cannot be used by a concurrently 
operating job, and the job will have 
to wait until the particular file is 
free. 



MOD 



causes logical positioning after the 
last record in the data set. It 
indicates that the data set already 
exists and that it is to be added to, 
rather than read. When MOD is 
specified and neither the volume 
serial number is given nor the data 
set cataloged or passed from an 
earlier job step, MOD is ignored and 
NEW is assumed. If the volume serial 
number is gi^ven, it is assumed that 
the data set is on the specified 
volume. 

DELETE 

causes the space occupied by the data 
set to be released for other purposes 
at the end of the current step. If 
the data set is cataloged, and the 
catalog is used to locate it, 
reference to the data set is removed 
from the catalog. If it is on a mass 
storage device, all references are 
removed from the volume table of 
contents, and the device space is made 
available for use by otner data sets. 
If the data set is on tape, the volume 
in which the data set resides is then 
available for use by ether data sets. 



KEEP 



ensures that the data set remains 
intact until a DELETE parameter is 
exercised in either the current jot> or 
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PASS 



some subsequent job. If the data set 
is on a mass storage device, it 
remains tabulated in the volume table 
of contents after completion of the 
job. When the volume containing the 
data set is to be dismounted, the 
operator is advised of the 
disposition. 



indicates that the data set is to be 
referred to in a later step of the 
current job, at which time its 
disposition may be determined. When a 
subsequent reference to this data set 
is encountered, its PASS status lapses 
unless another PASS is issued. The 
final disposition of the data set 
should be specified in the last DD 
statement referring to the data set 
within the current job. 

While a data set is in PASS status, 
the volume (s) on which it resides are, 
in effect, retained; that is, the 
system will attempt to avoid 
demounting them. If demounting is 
necessary, the system will ensure 
proper remounting, through operator 
messages. The unit name specified on 
the DD statement in the receiving step 
must be consistent with the unit name 
in the passing step. 

CATLG 

causes the creation, at the end of the 
job step, of an index entry in the 
system catalog pointing to the data 
set. The data set can be referred to 
by name in subsequent jobs, without 
the need for volume serial number or 
device type information from the 
programmer. Cataloging also implies 
KEEP. 

UNCATLG 

causes the index entry that points to 
this data set to be removed from the 
index structure at the end of this 
step. The data set is not deleted. 
If it is on a mass storage volume, 
reference to it remains in the volume 
table of contents. 

Not e; The absence of DELETE, KEEP, 
PASS, CATLG, and UNCATLG indicates 
that no special action is to be taken 
to alter the permanent or temporary 
status of this data set. If the data 
set was created in this job, it will 
be deleted at the end of the current 
step. If the data set existed before 
this job, it will be kept. 

The third subparameter indicates the 
disposition of the data set in the event 



the job step terminates abnormally. This 
is the conditional disposition 
subparameter. Explanations for DELETE, 
KEEP, CATLG, and UNCATLG are the same as 
those for normal termination. The 
following points should be noted when using 
the third subparameter. 



• If a conditional disposition is not 
specified and the job step abnormally 
terminates, the requested disposition 
(the second subparameter) is performed. 



• Data sets that were passed but not 

received by subsequent steps because of 
abnormal termination will assume the 
conditional disposition specified the 
last time they were passed. If a 
conditional disposition was not 
specified at that time, all new data 
sets are deleted and all other data 
sets are kept. 



• A conditional disposition other than 
DELETE for a temporary data set is 
invalid and the system assumes that it 
is DELETE. 



SYSOUT Parameter (Routing Data Set through 

the Outp ut St ream )_ 

schedules a printing or punching 
operation for the data set described 
by the DD statement. 



SYS OUT Subparameters : 

classname 

specifies the system output class on 
which the data set is to be written. 
A classname is an installation 
specified 1-character name designating 
the output class to which the data set 
is to be written. Each classname is 
related to a particular output unit. 
Valid values for the SYSOUT parameter 
are A through Z and through 9. A is 
the standard output class. Both data 
sets and system messages can be routed 
through the same output stream when 
using a priority scheduler. In this 
case, the output class selected for 
the data sets must be the same output 
class as that selected for the 
MSGCLASS parameter in the JOB 
statement. 

Note : Classes through 9 should not 
be used except in cases where the 
other classes are not sufficient. 
These classes are intended for future 
features of systems using priority 
schedulers. 
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(xt , proararn-name] [, form-no] ) 

is used for priority scheduling 
systems only. When priority 
schedulers are used, the data set is 
usually written on an intermediate 
mass storage device during program 
execution, and later routed through an 
output stream to a system output 
device. The x can be an alphabetic or 
numeric character specifying the 
system output class. Output writers 
route data from the output classes to 
system output devices. The DD 
statement for this data set can also 
include a unit specification 
describing the intermediate mass 
storage device and an estimate of the 
space required. If there is a special 
installation program to handle output 
operations, its program- name should be 
specified. Program-name is the member 
name of the program, which must reside 
in the system library. If the output 
data set is to be printed or punched 
on a specific type of output form, a 
4-digit form number should be 
specified. Form-no. is used to 
instruct the operator of the form to 
be used in a message issued at the 
time the data set is to be printed. 



Notes 



If both the program-name and form-no. 
are omitted, the delimiting parentheses 
can be omitted. 



(SYS1.LINKLIB) . Use of JOBLIB results in 
the system library being combined with the 
private library for the duration of a job; 
use of STEPLIB, for the duration of a job 
step. During execution, the library 
indicated in tnese statements is scanned 
for a module before the system library is 
searched. 

The JOBLIB DD statement must appear 
immediately after the JOB statement and its 
operand field must contain at least the 
DSNAME and DISP parameters. The DISP 
parameter must contain PASS as the second 
subparameter if the library is to be made 
available to later job steps. Only one 
JOBLIB statement may be specified for a job 
but more than one library may be specified 
on a JOBLIB statement. The JOBLIB 
statement is meant to concatenate existing 
private libraries with the system library. 
It need not be specified for load modules 
created in the job or for permanent members 
of the system library (see "Checklist for 
Job Control Statements" and "Libraries" for 
examples) . 

The STEPLIB DD statement may appear in 
any position among the DD statements for 
the job step. The library should be 
defined as OLD. If the library is to be 
passed to other job steps, the second 
subparameter of the DISP parameter should 
be coded PASS. A later job step may then 
refer to the library by coding its STEPLIB 
DD statement as follows: 



If the Direct SYSOUT Writer is used to 
write a data set, both the form-no. 
and program-name are ignored. All 
parameters on the DD statement, i.e., 
UNIT or SPACE, are also ignored. 



//STEPLIB DD DSNAME=*.Stepname. STEPLIB, X 
// DISP=( OLD, PASS) 



The STEPLIB statement overrides the 
JOBLIB statement if both are present in a 
job step. 



ADDITIONAL DD STATEMENT FACILITIES 



By specifying certain ddnames, the 
programmer can request tne operating system 
to perform additional functions. The 
operating system recognizes these 
special-purpose ddnames: 

• JOBLIB and STEPLIB to identify private 
user libraries 

• SYSABEND and SYSUDUMP to identify data 
sets on which a dump may be written 



JOBLIB AND STEPLIB DD STATEMENTS 



SYSABEND AND SYSUDUMP DD STATEMENTS 



The ddnames SYSABEND or SYSUDUMP 
identify a data set on which an abnormal 
termination dump may be written. The dump 
is provided for job steps subject to 
abnormal termination. 

The SYSABEND DD statement is used when 
the programmer wishes to include in his 
dump the problem program storage area, the 
system nucleus, and the trace table if the 
trace table option had been requested at 
system generation time. 



The JOBLIB and STEPLIB DD statements are 
used to concatenate a user* s private 
library with the system library 



The SYSUDUMP DD statement is used when 
the programmer wishes to include only tne 
problem program storage area. 
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The programmer may rout the dump 
directly to an output writer by specifying 
the SYSOUT parameter on the DD statement. 
In a multiprogramming environment, the 
programmer may also define the intermediate 
direct-access device by specifying the UNIT 
and SPACE parameters. 



operand field specifies the job name, unit 
name, or other information being 
considered. 



Note: 



A command statement cannot be 



continued, it must be coded on one card or 
card image. 



PROC STATEMENT 



The PROC statement may appear as the 
first control statement in a cataloged 
procedure and must appear as the first 
control statement in an in-stream 
procedure. The PROC statement must contain 
the term PROC in its operation field. For 
a cataloged procedure, the PROC statement 
assigns default values to symbolic 
parameters defined in the procedure; its 
operand field must contain symbolic 
parameters and their default values. The 
PROC statement marks the beginning of an 
in-stream procedure; its operand may 
contain symbolic parameters and their 
default values. 



DELIMITER STATEMENT 



The delimiter statement marks the end of 
a data set in the input stream. The 
identifying characters /* must be coded 
into columns 1 and 2, the other fields are 
left blank. Comments are coded as 
necessary. 



Note : When using a system with MFT or MVT, 
the end of a data set need not be marked in 
an input stream that is defined by a DD * 
statement. 



PEND - STATEMENT 



The PEND statement must appear as the 
last control statement in an in-stream 
procedure and marks the end of the 
in-stream procedure. It must contain the 
term PEND in the operation field. The PEND 
statement is not used for cataloged 
procedures. For further information about 
in-stream procedures, see "Testing a 
Procedure as an In-Stream Procedure" in 
"Using the Cataloged Procedures. " 



NULL STATEMENT 



The null statement is used to mark the 
end of certain jobs in an input stream. If 
the last DD statement in a job defines data 
in an input stream, the null statement 
should be used to mark the end of the job 
so that the card reader is effectively 
closed. The identifying characters // are 
coded into columns 1 and 2, and all 
remaining columns are left blank. 



COMMAND STATEMENT 



The operator issues commands to the 
system via the console or a command 
statement in the input stream. Commands 
can also be issued to the system via a 
command statement in the input stream. 
However, this should be avoided since 
commands are executed as they are read 
(except for SET and START in systems with 
PCP) and may not be synchronized with 
execution of job steps. Command statements 
must appear immediately before a JOB 
statement, an EXEC statement, a null 
statement, or another command statement. 

The command statement contains 
identifying characters (//) in columns 1 
and 2, a blank name field, a command, and, 
in most cases, an operand field. The 



COMMENT STATEMENT 



The comment statement is used to enter 
any information considered helpful by the 
programmer. It may be inserted anywhere in 
the "iob control statement stream after the 
JOB Statement. (The comment statement 
contains a slash in columns 1 and 2, and an 
asterisk in column 3. The remainder of the 
card contains comments. ) Comments are 
coded in columns 4 through 80, but a 
comment may not be continued onto another 
statement. 

When the comment statement is printed on 
an output listing, it is identified by the 
appearance of asterisks in columns 1 
through 3. 
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BATCH COMPILATION 



The catch compile feature is used to 
compile multiple programs or subprograms 
with one invocation of the compiler. The 
object programs produced from the batch 
compilation may be link-edited into either 
one load module or separate load modules. 

This feature must be requested at 
compile time by specification of BATCH in 
the PARM field or, if a cataloged procedure 
is used, in the PARM. COB field of the EXEC 
card. In the BATCH mode, all options 
specified on the EXEC card, as well as all 
default options, apply to every program in 
the batch unless specific options are 
overridden, via the CBL card, for an 
individual compilation. 

The CBL card must be the first card in 
each program within a batch mode. The CBL 
card, used to specify additional compiler 
options or to change existing options for 
that individual program, has the following 
format: 



CBL [option 1] [, option 2] 



The letters CBL may appear in any three 
consecutive columns 1 through 72, and the 
option (s) specified may be any PARM 
compiler option(s) except SIZE, BUF, and 
BATCH, which are ignored if indicated. 

Note s : 

• A sequence number may appear in columns 
1 through 6 of the CBL card. 

• Any option given on the CBL card 
overrides options on the EXEC card for 
this compilation only, except where the 
option requires the use of a file 
desired in a subsequent compilation 
(for example, LOAD and SYSLIN) . In 
such a case, the option must be 
specified either as a default or as an 
option on the EXEC card. This is not 
to imply that the option cannot be 
negated on any CBL card when it is not 
desired. 

• If a CBL card is present and BATCH is 
not specified on the EXEC card, the CBL 
card is regarded as an invalid 
statement. 

• If the compiler NAME option is 
specified on the CBL card, a linkage 
editor NAME control card is generated 



for this compilation, facilitating the 
link-editing of the program into a 
separate load module. 



« The output of a batch compilation may- 
be executed immediately only if it is 
made up of a single load module (for 
example, a main program and 
subprograms). In order for this load 
module to be executed, the member name 
specified at compile time must be 
specified at execution time. 

• The batch option may be used in 
conjunction with BASIS. This facility 
provides the COBOL programmer with the 
ability to combine a (multiple) BASIS 
library member (s) and/or a (multiple) 
COBOL source program(s) with one 
invocation of the compiler. 

• The BATCH option and the SYMDMP option 
are mutually exclusive. 

When the batch option is used in 
combination with BASIS, the following rules 
apply: 

1. All the BASIS library members to be 
compiled must be members of the 
partitioned data set(s) referred to oy 
the SYSLIB DD data set name(s). 

2. Each BASIS library member must contain 
only one source program. 

Figure 9 shows that with one invocation 
of the COBUCL cataloged procedure (see the 
chapter "Using the Cataloged Procedures"), 
the programs COMPILE1, C0MPILE2, and 
C0MPILE3 are compiled and two load modules 
created as follows: 

1. C0MPILE1 and C0MPILE2 are link-edited 
together to form one load module with 
the member name of C0MPILE2, a typical 
called/calling situation. (For 
further discussion of articulation 
between COBOL programs, see the 
chapter "Called and Calling 
Programs".) In this case, the entry 
point of the load module is still the 
first program, C0MPILE1. 

2. C0MPILE3 is link-edited to create the 
load module with the member name of 
C0MPILE3. 

Figure 10 shows that with one invocation 
of the COBUCL procedure the programs PR0G1 
and PR0G2 and BASIS library members PAYROLL 
and PAYROLL2 are compiled and four load 
modules are created. (An example of how to 
execute load modules created with the BATCH 
feature using the procedure COBUCL is given 
in Figure 9. ) 



//jobname JOB 
//COMPILE EXEC* 

//COB. SYSIN DD 
CBL NONAME 

ID DIVISION. 

PROGRAM-ID. COMPILE1. 



1, BATCH, MSGLEVEL=1 

COBUCL, PARM. COB=» BATCH, NAME' 

* 



CBL NAME 

ID DIVISION. 
PROGRAM- ID. 



CBL NAME 

ID DIVISION. 
PROGRAM- ID. 



COMPILE2. 



COMPILE3. 



DSN=BATCHRUN r SPACE=(TRK, ( 10, 5, 2 )),... . 



/* 

//LKED. SYSLMOD DD 

/* 

//COMPILE2 EXEC PGM=COMPILE2 

//STEPLIB 2 DD DSN=BATCHRUN 2 ,DISP=SHR, .. 

// (Cards needed to execute COMPILE1 and COMPILE2) 

/* 

//COMPILE3 EXEC PGM=COMPILE3 

//STEPLIB DD DSN=BATCHRUN ( DISP=SHR, 

// (Cards needed to execute COMPILE3) 
/* 



x In the compile step, no special JCL is needed for SYSLIN because the COBUCL cataloged 

procedure is used (see the chapter "Using The Cataloged Procedures"). 
2 In the link-edit step, a partitioned data set is created with the DSN of BATCHRUN. 

L — , 

Figure 9. Example of a Batch Compilation 



//jobname 
//COMP 

//COB. SYSLIB 
//COB. SYSIN 
CBL 



CBL 
BASIS 

CBL 
BASIS 

CBL 



//LKED. SYSLMOD 3 
/* 



JOB 1 , BATBASIS , MSGLEVEL=1 

EXEC COBUCL, PARM. COB=' BATCH, NAME, LIB' 

DD DSN=LIBPOS, . . . *■ 

DD * 

NAME, NOLIB 

IDENTIFICATION DIVISION. 

PROGRAM- ID. PROG1. 

NAME, LIB 

PAYROLL 2 

NAME, LIB 

PAYROLL 2 

NAME, NOLIB 

IDENTIFICATION DIVISION 

PROGRAM- ID. PROG2. 



DD 



DSN=BATCHBAS,SPACE=(TRK, (10, 5,2) ), 



^-This partitioned data set contains as separate members PAYROLL and PAYROLL2. 
2 Example as shown in Figures 76-78. 

3 The load modules of these four COBOL programs exist as separate members of a 
partitioned data set named BATCHBAS. 

L 

Figure 10. Creation of Four Load Modules with Programs PROG1 and PROG2 and BASIS 
Library Members PAYROLL and PAYROLL2 
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DATA SE T R EQUIREMENTS 



COMPILER 



classes for each data set. (See "Appendix 
D: Compiler Optimization" for further 
information on blocked compiler data sets 
other than utility data sets. ) 



Eleven data sets may be defined for a 
compilation job step; six of these (SYSUTl, 
SYSUT2, SYSUT3, SYSUT4, SYSIN, and 
SYSPRINT) are required. A seventh data set 
SYSUT5, is required if the SYMDMP option is 
invoked. The other three data sets 
(SYSLIN, SYSPUNCH, and SYSLIB) are 
optional. 

For compiler data sets other than 
utility data sets, a logical record size 
can be specified by using the LRECL and 
BLKSIZE subparameters of the DCB parameter. 
The values specified must be permissible 
for the device on which the data set 
resides. LRECL equals the logical record 
size, and BLKSIZE equals LRECL multiplied 
by n, where n is equal to the blocking 
factor. If this information is not 
specified in the DD statement, it is 
assumed that the logical record sizes for 
the unblocked data sets have the following 
default values: 



Unblocked 

Data Set 

SYSIN 

SYSLIN 

SYSPUNCH 

SYSLIB 

SYSPRINT 

SYSTERM 



Default 
Value (bytes) 

80 

80 

80 

80 
121 
121 



Note : When using the SYSUTl, SYSUT2, 
SYSUT3, SYSUT4, SYSUT5, SYSPRINT, SYSPUNCH, 
or SYSLIN data sets, the following should 
be considered: If the primary space 
allocated for the data set is insufficient 
when compiling large programs, an area of 
core storage may be used to complete 
processing. This area would be used for an 
extra data extent block (DEB) and would be 
in the middle of the compiler's required 
core. Therefore, enough contiguous space 
may not be available to load a compiler 
phase. Such a condition will result in an 
abnormal termination of the job. The 
programmer should therefore attempt to 
allocate sufficient primary space to 
eliminate the need for a secondary 
allocation of space. See the Program 
Product publication IB M OS Full American 
Nati onal Sta nda rd COB O L Compi l er and 

L ibr ary, Versi on 3, Ins tallatio n Reference 

Material for information on storage 
estimates for compile data sets. 

The ddname that must be used in the DD 
statement describing the data set appears 
as the heading for each description that 
follows. Table 5 lists the function, 
device requirements, and allowable device 



SYSUTl, SYSUT2, SYSUT3, SYSUT4, SY SUT5 



The DD statements using these ddnames 
define utility data sets that are used by 
the compiler when processing the source 
module. The data set defined by the SYSUTl 
DD statement must be on a mass storage 
device. Except for SYSUT5, which is needed 
at execution time, these data sets are 
temporary and have no connection with any 
other job step. For example, the DD 
statement 

//SYSUTl DD UNIT=SYSDA, SPACE=(TRK, (40,10)) 

specifies that the data set is to be 
written on any available mass storage 
device, with a primary allocation of 40 
tracks. Additional tracks, if required, 
are to be allocated in groups of 10. The 
data set is to be deleted at the end of the 
job step (by default). 



SYSIN 



The data set defined by the SYSIN DD 
statement contains the input for the 
compiler, i.e., the source module 
statements that are to be processed. The 
input/output device assigned to this data 
set can be either the device transmitting 
the input stream (the device designated as 
SYSIN at system generation time) or a 
device designated by the programmer. When 
using a cataloged procedure, the DD 
statement describing this data set usually 
appears in the input stream. For example, 



//SYSIN 



DD 



specifies that the input data set follows 
in the input stream. If the asterisk or 
DATA convention is used, the SYSIN DD 
statement must be the last DD statement in 
the job step. 



SYSPRINT 



This data set is used by the compiler to 
produce a listing. Output may be directed 
to a printer, a mass storage device, or a 
magnetic-tape device. The listing will 
include the results of the default or 
specified options of the PARM parameter 



04 



I i.e. , diagnostic messages, the object code 
listing) . For example, in the DD statement 

//SYSPRINT DD SYSOUT=A 

SYSOUT is the disposition for printer data 
sets, and A is the standard output class 
for printer data sets. 



The temporary name of the data set is 
GOFILE, the parameter DISP=( MOD, PASS) 
indicates that the data is to be created or 
added to in this job step and is to be 
passed to another job step, which may be 
the linkage editor step. The device to be 
assigned for storage is a mass storage 
device on which 30 tracks are initially 
allocated to the data set. If more space is 
needed, tracks are allocated 10 at a time. 



SYSPUNCH 



The data set defined by the SYSPUNCH DD 
statement is used to punch an object module 
deck. This data set can be directed to a 
card punch, mass storage device, or 
magnetic tape. For example, in the DD 
statement 



Note: The SYSLIN DD statement is not 
required if NOLOAD is in effect. SYSLIN 
may be either a data set or a member of a 
PDS. 



SYSLIB 



//SYSPUNCH DD SYSOUT=B 

SYSOUT is the disposition for punch data 
sets, and B is the standard output class 
for punch data sets. 

Note: The SYSPUNCH DD statement is not 
required if NODECK is in effect. SYSPUNCH 
may be either a sequential data set or a 
member of a PDS. 



SYSLIN 



The SYSLIB DD statement defines the 
library (PDS) that contains the data 
requested by a COPY statement (in the 
source module) or by a BASIS card in the 
input stream. Note that more than one 
partitioned data set may be used for the 
library function by concatenating them with 
SYSLIB (see "Libraries" for an example). 
Libraries must always be on mass storage 
devices. Only one SYSLIB statement may be 
used in a compilation job step. For 
example, in the DD statement 

//SYSLIB DD DSNAME=USERLIB,DISP=OLD 



The device defined by the SYSLIN DD 
statement is used by the compiler to store 
an object module. It may be on a mass 
storage or magnetic tape device. For 
example: 



//SYSLIN DD 

// 

// 

// 



DSNAME=SS GOFILE, 
DISP= (MOD, PASS), 
UNIT=SYSDA, 
SPACE=(TRK, (30,10)) 



the name of the library is USERLIB, and 
DISP=OLD indicates that the library has 
been created in a previous job and is 
cataloged, or has been created in a 
previous step in this job. No other 
information need be given if the specified 
library has been cataloged. 

Note: The SYSLIB DD statement is not 
required if NOLIB is in effect. 
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Table 5. Data Sets Used for Compilation 
r t t 



ddname 



Type 



Function 



Device 
Requirements 



+- 



Allowable 
Device Classes 



SYSIN 
(required) 



Input/output 



Reading the source 
program 



Card reader 
Intermediate storage 



SYSSQ, SYSDA, or the 
input stream device 
(specified by DD * 
or DD DATA) 



SYSPRINT 
(required) 



Writing the storage 
map, listings, and 
and messages 



+- 



Printer 
Intermediate storage 



SYSSQ, SYSDA, stand- 
ard output class A 



SYSPUNCH 
(optional) 



Punching the object 
module deck 



Card punch 
Mass storage 
Magnetic tape 



SYSLIN 
(optional) 



Creating an object 
module data set as 
output from the com- 
piler and input to 
the linkage editor 



Mass storage 
Magnetic tape 



SYSCP, SYSSQ, SYSDA, 
standard output 
class B 



4- 



SYSSQ, SYSDA 



SYSUTl 
(required) 



Utility 



SYSUT2 
(required) 



Work data set needed 
by the compiler 
during compilation 



Mass storage 



SYSUT3 
(required) 



Work data set needed 
by the compiler 
during compilation 



Mass storage 
Magnetic tape 



Work data set needed 
by the compiler 
during compilation 



Mass storage 
Magnetic tape 



SYSUT4 
(required) 



SYSUT5 



Work data set needed 
by the compiler 
during compilation 



Mass storage 
Magnetic tape 



Work data set needed 
when the SYMDMP 
option is in effect 



Mass storage 
Magnetic tape 



SYSDA 



SYSSQ, SYSDA 



SYSSQ, SYSDA 



4- 



SYSSQ, SYSDA 



SYSSQ, SYSDA 



SYSLIB 
(optional) 



Library 



Optional user source 
program library 



Mass storage 



SYSDA 



Note : Once created, a SYSUT5 data set can be moved only to a device of the same class. 
That is, if the SYSUT5 data set is put on tape at compile time, that data set cannot be 
moved to a disk at execution time. The SYSUT5 data set must be unblocked. 



LINKAGE EDITOR 



SYSLIN 



Five data sets are required for linkage 
editor processing. Others may be necessary 
if secondary input is specified. In the 
following discussions, the ddname that must 
be used in the DD statement describing the 
data set appears as the heading for each 
description of the particular data set. 
For any user-defined data set, the ddname 
is defined by the programmer. Table 6 
lists the function, device requirements, 
and allowable device classes for each data 
set. 



The SYSLIN DD statement defines the data 
set that is primary input to linkage editor 
processing. Normally this data set 
consists of the output from a previous 
compilation job step. The primary input 
may also be linkage editor control 
statements, such as the INCLUDE, LIBRARY, 
or OVERLAY statements (see "Calling and 
Called Programs"). The input device 
assigned to this data set is either the 
device transmitting the input stream, if 
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Table 6. Data Sets Used for Linkage Editing 
r t T T" 



ddname 



Type 



4- 



Function 



Device 
Requirements 



+- 



Allowable 
Device Classes 



SYSLIN 

(required) 



Input/ 
output 



Primary input data, 
normally the output 
of the compiler 



Mass storage 
Magnetic tape 
Card reader 



SYSSQ, SYSDA, or the input 
stream device (specified 
by DD * or DD DATA) 



SYSPRINT 
(required) 



Diagnostic messages 
Informative messages 
Module map 
Cross-reference list 



Printer 
Intermediate 
storage 



SYSSQ, standard output 
class A 



SYSLMOD 

(required) 



Output data set for 
the load module 



4- 



Mass storage 



SYSDA 



-+- 



SYSUTl 

(required) 



Utility 



Work data set 



Mass storage 



SYSDA 



4- 



SYSLIB 

(required) 
for COBOL 
Library 
subroutines 



Library 



Automatic call library 
(SYS1.C0BLIB is the 
name of the COBOL 
subroutine library) 



Mass storage 



SYSDA 



User-specified 
(optional) 



Additional object 
modules and load 
modules 



Mass storage 
Magnetic tape 



SYSDA, SYSSQ 



the input is an object module deck, or a 
device designated by the programmer. 
However, the data set may simply be passed 
from the previous compilation job step. 
For example, in the DD statement 



//SYSLIN DD DSNAME=*.STEPNAME. SYSLIN, 
// DISP= ( OLD, DELETE ) 



X 



the data set is defined in the SYSLIN DD 
statement contained in the compiler job 
Step, STEPNAME. DISP= (OLD, DELETE) 
indicates that the data set was created in 
a previous job step and is to be deleted at 
the end of this job step. 



SYSLMOD 



The SYSLMOD DD statement defines the 
output data set, in this case the load 
module. The load module must be placed in 
a library as a named member. The library 
can be the Link Library (SYSl. LINKLIB) or a 
private user-defined library. Such 
libraries must always reside on a mass 
storage device, and space for the library 
is allocated when the library is created. 
For example, in the DD statement 

//SYSLMOD DD DSNAME=SYS1. LINKLIB (MEMBER) , X 
// DISP=OLD 



SYSPRINT 



The data set defined by the SYSPRINT DD 
statement is used by the linkage editor to 
produce a listing. For example: 

//SYSPRINT DD SYSOUT=A 

Output may be directed to a printer or to 
magnetic tape. The listing may include any 
options specified by the PARM parameter of 
the EXEC statement (a module map or cross 
reference list, diagnostic or informative 
messages, etc.). 



the load module, MEMBER, is stored as a 
member of the link library. DISP=OLD 
indicates that the library is already 
created and additions are to be made to it. 

//SYSLMOD DD DSNAME=LIBl (BALANCE) , X 

// DISP= ( NEW, CATLG ) , X 

// V0LUME=SER=111111, X 

// SPACE=(TRK, (40,10,1) ), X 

// UNIT=SYSDA 



The load module, BALANCE, is to be a member 
of a library, LIB1, which is to be created 
in this job step, with BALANCE as its first 
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member. The mass storage volume to which 
it is directed is identified by the serial 
number, 111111. A primary quantity of 40 
tracks is allocated to the library with an 
additional allocation for one 256-byte 
record to be used for the directory. If 
more space is needed for the library, 
tracks are added, 10 at a time. (However, 
no additional space can be allocated for 
the directory. ) 



User-Specified Data .Sets 



Additional data sets may be defined for 
linkage editor processing. These data sets 
may be used as additional input sources of 
object modules or load modules. They may 
also be concatenated with the primary input 
data set or the automatic call library 'see 
"Libraries"). 



Note : If the load module is placed in a 
private library, the JOBLIB DD statement 
must be specified in subsequent jobs that 
execute load modules from the library. 



LOADER 



SYSUT1 



The SYSUTl DD statement defines a 
utility data set used by the linkage editor 
when processing object modules and load 
modules. The data set must be on a mass 
storage device. It is a temporary data set 
and has no connection with any other job 
step. For example: 

//SYSUTl DD UNIT=SYSDA, SPACE=(TRK, (40, 10) ) 



One data set (SYSLIN) is required for 
loader processing. Two are optional 
(SYSLIB, SYSLOUT). (These ddnames can be 
changed during system generation with the 
LOADER macro instruction. ) In addition, 
any DD statements and data required by the 
loaded program must be included in the 
input deck. 

In the following discussions, the 
default ddname for the DD statement 
describing the data set appears as the 
heading for each description of the 
particular data set. 



The data set is initially allocated 40 
tracks on any available mass storage 
device. If more space is needed, tracks 
are added, 10 at a time. A temporary name 
is assigned to the data set for the job 
step. 



SYSLIB 



The SYSLIB DD statement assigns the 
named partitioned data set to the automatic 
call library from which modules may be 
automatically obtained by the linkage 
editor to resolve external references. 



SYSLIN 



The SYSLIN DD statement defines the data 
set that is primary input to the loader. 
This input can be either object modules 
produced by the COBOL compiler or load 
modules produced by the linkage editor, or 
both. The loader allows both object module 
and load module concatenation on SYSLIN. 
The data sets defined by the SYSLIN DD 
statements can be either sequential data 
sets or members of a partitioned data set. 



//SYSLIB DD DSNAME=SYSl.COBLIB,DISP=SHR 



SYSLIB 



This statement assigns the COBOL subroutine 
library to the automatic call library. 
When there is a possibility that the 
compiler may have generated calls to any 
COBOL library subroutines, the SYSLIB 
statement must be specified (see "Appendix 
B: COBOL Library Subroutines" for a list 
of library subroutines, their functions, 
and entry points). 

Note: The SYSLIB statement can also define 
a sequential data set (see "Libraries"). 



The SYSLIB DD statement defines the data 
set containing IBM or user-written library 
routines to be included in the loaded 
program. The SYSLIB data set is searched 
when unresolved references remain after 
processing SYSLIN and, optionally, 
searching the link pack area of MVT or the 
resident reusable routine of MFT. The 
library may contain either object modules 
or load modules but not both. The data set 
defined by the SYSLIB DD statement must be 
a partitioned data set. 
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SYSLOUT 



The SYSLOUT DD statement defines the 
data set used for error and warning 
messages and for an optional map of 
external references. The record format of 
SYSLOUT must be FA, FBA, or FBSA. 



EXECUTION TIME DATA SETS 



Any number of data sets may be used for 
execution time processing. These data 
sets, or files, are identified in the 
source program, and each must be described 
by a DD statement. The ddname is used to 
link the DD statement to the COBOL ASSIGN 
clause in the source program that specifies 
the ddname. DD statement requirements for 
the DISPLAY, ACCEPT, EXHIBIT, and TRACE 
statements are discussed in the following 
text. DD statements that specify COBOL 
debugging aids and an abnormal termination 
dump are also discussed. Use of either the 
Sort or the RERUN feature requires 
additional DD statements. For information 
about these statements, see "Using the Sort 
Feature" and "Using the Checkpoint/Restart 
Feature. " 



DISPLAY Statement 



where : 

n is the blocking factor 



SYSPUNCH must be on a device where blocking 
is permitted. For example: 



//SYSPUNCH 

// 

// 

// 



DD UNIT=SYSSQ, 

DCB=(RECFM=FB, 

BLKSIZE=160), 

LABEL=(,NL) 



When the UPON option is omitted, SYSOUT is 
the default option. 



Examp_le_2: 



DISPLAY 



\identif iei 



/literal 
//SYSOUT DD applicable parameters 

It is assumed that SYSOUT is an 
unblocked data set that has a line width of 
121 characters (1-byte per control 
character) . 

For example: 

//SYSOUT DD SYSOUT=A 



The DISPLAY statement requires an 
associated DD statement unless the data is 
to be displayed on the console. The DD 
statements needed for each form of the 
DISPLAY statement are as follows: 



Examp le 1 : 

jidentif ierl 
DISPLAY \ i ...UPON SYSPUNCH 

(literal 



//SYSPUNCH DD applicable parameters 



It is assumed that SYSPUNCH is an 
unblocked data set that has a logical 
record length of 80 characters. For 
example: 

//SYSPUNCH DD SYSOUT=B 



However, the programmer can specify a 
blocked data set by using the subparameters 
of the DCB parameter as follows: 

RECFM=FB, BLKSIZE=n*8 



However, the programmer can specify an 
alternate line width, recording mode, 
and/or a blocked data set by using the DCB 
parameter. To specify an alternate line 
width, the subparameters of the DCB 
parameter are used as follows: 

LRECL=line width+l,BLKSIZE=LRECL value 



To specify a blocked data set, the 
subparameters are used as follows: 

RECFM=FBA, LRECL=line width+1, 
BLKSIZE=n*(LRECL value), 

where : 

n is a blocking factor 



SYSOUT must be on a device where blocking 
is permitted. The extra character in LRECL 
allows for the carriage control character. 
For example, to specify an alternate line 
width, the following SYSOUT statement can 
be used. 

//SYSOUT DD SYSOUT=A,DCB=(LRECL=133, X 
// BLKSIZE=133) 
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To specify a blocked data set, the 
following SYSOUT statement can be used. 

//SYSOUT DD DSNAME=PRINTOUT, 

// UNIT=SYSDA, . . . , 

// DCB=(RECFM=FBA, 

// LRECL=121, 

// BLKSIZE=605), 

// V0LUME=SER=111111 



The DISPLAY statement can use a 
mnemonic-name rather than a system-name. 



DISPLAY 




. . . UPON mnemonic-name 



where mnemonic-name is associated with the 
word SYSPUNCH or SYSOUT in the Environment 
Division. 



// 



\sYSPUNCH 



SYSOUT 



DD applicable parameters 



For example: 

//SYSIN DD * 

(data) 
/* 

However, the programmer can specify a 
blocked data set by using the subparameters 
of the DCB parameter as follows: 

RECFM=FB, BLKSIZE=n*80 

where : 

n is the blocking factor 

SYSIN must be on a device where blocking is 
permitted. For example: 



//SYSIN DD UNIT=2400, . .. , 

// DCB=(RECFM=FB, 

// BLKSIZE=160), 

// LABEL=(,NL) 



If a logical record length of other than 80 
characters is desired, it must be specified 
in the LRECL field of the DCB parameter. 



EXHIBIT or TRACE Statement 



ACCEPT Statement 



The ACCEPT statement requires an 
associated DD statement unless either the 
data is being accepted from the console or 
format 2 of the ACCEPT statement is used 
(making possible use of the options DATE, 
DAY, and TIME). The DD statements for each 
form of the ACCEPT statement are as 
follows: 



Exa m ple 1 : 

ACCEPT identifier 

When the FROM option is omitted, SYSIN is 
the default option. 

//SYSIN DD applicable parameters 

E xam ple 2 : 

ACCEPT identifier FROM mnemonic-name 

where mnemonic-name is associated with the 
word SYSIN in the Environment Division. 

//SYSIN DD applicable parameters 

It is assumed that SYSIN is an unblocked 
data set that has a logical record length 
of 80 characters. 



The EXHIBIT or TRACE statement requires 
a SYSOUT DD statement as discussed for 
DISPLAY. 



Note : If the job step already includes a 
SYSOUT DD statement for some other use, 
another may not be inserted since all 
SYSOUT output from any source in the job 
step will be merged onto the one SYSOUT 
data set defined for that job step. 



COBOL D e bugging Aids 



If one or more of the options FLOW, 
STATE, and SYMDMP is in effect, the 
following DD statement must be used: 

//SYSDBOUT DD applicable parameters 

If the output is routed through the output 
stream and written on a system output 
device, the following may be used: 



//SYSDBOUT 



DD 



SYSOUT=A 



The recording mode is FBA. The user 
can, however, specify a blocked data set 
and alternate recording mode by using the 
DCB subparameters. 



Note : It is assumed that SYSDBOUT is an 
unblocked data set that has a line width of 
121 bytes (one byte for a control 
character) . 



Abnormal Termination Dump 



To obtain an operating system 
hexadecimal dump in case the job is 
abnormally terminated, one of the following 
DD statements must be used: 

//SYSABEND DD applicable parameters. 

//SYSUDUMP DD applicable parameters. 

The dump provided when the SYSABEND DD 
statement is used includes the system 
nucleus, the program storage area, and a 
trace table, if the trace table option was 
reguested at system generation. The 
SYSUDUMP DD statement provides a dump of 
the program storage area. The applicable 
parameters are those for a standard 
seguential data set. If the dump is routed 
through the output stream and written on a 
system output device, the following DD 
statement may be used: 



//SYSUDUMP DD SYSOUT=A 



Note : If a COBOL program abnormally 
terminates, then a formatted dump is 
provided for all COBOL programs compiled 
with the SYMDMP option which could include 
the abnormally terminating program and its 
callers, up to and including the main 
program. The //SYSABEND or //SYSUDUMP DD 
card need not be included. For a 
discussion of the symbolic dumping option, 
as well as of other COBOL symbolic 
debugging options, see the chapter entitled 
"Symbolic Debugging Features. " 



COBOL Subroutine Library 



The user should concatenate a library of 
selected COBOL object-time subroutines with 
the link library as soon as the compiler is 
installed. (For information on how this 
can be accomplished, see the section 
"Sharing COBOL Library Subroutines" in the 
chapter entitled "Libraries"). 
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USER FILE PROCESSING 



USER-DEFINED FILES 



SELECT MASTER ASSIGN TO 
DA-2302-D-MASTERA. . . 



Files that are processed in a COBOL 
program must be described as data sets to 
the operating system. Whenever a file is 
specified in a program by the following 
statement: 



In that case, the following DD statements, 
u sed at different times , would assign the 
different named data sets to the program: 



SELECT [OPTIONAL] file-name 
ASSIGN TO system-name 



//MASTERA DD DSNAME=MASTER1, . . . 
//MASTERA DD DSNAME=MASTER2, . . . 
//MASTERA DD DSNAME=MASTER3, . . . 



this file must be described in an FD 
file-name entry and in a DD statement in 
the execution-time job step. The ddname in 
the DD statement is a portion of the 
system-name specified in the ASSIGN TO 
clause. In the system-name 

UT-2400-S- T AXR ATE 



TAXRATE is the ddname portion of the 
system-name. 

Note : The device-number specified in the 
system-name is ignored used by the 
compiler. Actual device allocation is a 
function of the DD statement. 



FILE NAMES AND DATA SET NAMES 



The terms "file" (COBOL usage) and "data 
set" (operating system usage) have 
essentially the same meaning. There may, 
however, be a difference between the 
file-name and the data set name. The data 
set name always represents a specific data 
set. The file-name can, at different 
times, represent different data sets. The 
DD statement allows a programmer to select, 
at the time his program is executed, the 
specific data set that is to be associated 
with a particular file-name. This facility 
can be especially powerful when applied to 
input data sets. 

The file-name is a name known within the 
COBOL program. Changing a file-name 
requires changing input/output statements 
and recompiling the program. Changing a DD 
statement when a program is executed is a 
simple procedure. 

As an example, consider a COBOL program 
that might be used in exactly the same way 
for several different master files. It 
might contain the clause 



If the first DD statement appears in the 
job step that calls for execution of the 
program, any reference within the program 
to MASTER is a reference to the data set 
named MASTERl ; if the second DD statement 
appears, the reference is to MASTER2; if 
the third, the reference is to MASTER3. 

However, if a file-name within a program 
is always to be applicable to only a single 
data set, the names might be written as 
follows: 

SELECT TAXRATE ASSIGN TO 
UT-2400-S-TAXRATE. . . 



The applicable DD statement might be: 

//TAXRATE DD DSNAME=TAXRATE, . . . 

Of the names, the ddname portion of the 
system-name that appears in the ASSIGN 
clause and the ddname of the DD statement 
must always be the same. The file-name and 
the data set name may be the same, or they 
may be different. (Of course, the 
file-name in the SELECT sentence must be 
the same as the FD name. ) 

If two or more files on direct-access 
devices have the same ddname and are open 
at the same time (i.e., the output from the 
files is being merged into one data set) , 
the files must have no conflicting 
attributes. The foregoing also applies to 
SYSOUT data sets if they are written on an 
intermediate direct-access device. 

The use of the DISPLAY, EXHIBIT, or 
READY TRACE verbs causes the compiler to 
open its own file whose ddname is SYSOUT. 
If the programmer has also assigned one of 
his output files to SYSOUT, he must ensure 
that he has opened, written, and closed his 
file before the first execution of any of 
the previously mentioned verbs. 



SPECIFYING INFORMATION ABOUT A FILE 



FILE PROCES SING T ECHNI QUES 



Some of the information about the file 
must always be specified in the FD entry, 
SELECT sentence, APPLY, and other COBOL 
clauses. Other information must be 
specified in the DD statement. For 
example, the amount of space allocated for 
a mass storage output file must be 
specified in the DD statement by the SPACE, 
SPLIT, or SUBALLOC parameters. Certain 
characteristics of files cannot be 
expressed in the COBOL language, and may be 
specified on the DD statement for the file 
by the DCB parameter. This parameter 
allows the programmer to specify 
information for completing the data control 
block associated with the file (see 
"Additional File Processing Information" 
for a discussion of the data control block, 
and "Appendix C: Fields of the Data 
Control Block" ) . 



DATA SET ORGANIZATION 



A data set used by a COBOL program can 
have one of four types of organization: 
standard sequential, direct, relative, and 
indexed. The first type (sequential) may 
be on any input/output device. All other 
types must be on mass storage devices (see 
Figure 11 for information in determining 
the file processing technique to be used, 
according to data set organization) . 



A s ta ndar d s equ ential data set is one 
in which records are organized solely 
on the basis of their successive 
physical positions. 



Each file used in the program must be 
referred to by a particular file processing 
technique. Four processing techniques are 
discussed in this publication. They are 
standard sequential (QSAM) , direct (BSAM, 
BDAM), relative (BSAM, BDAM) , and indexed 
(QISAM, BISAM). 

A fifth processing technique, called 
partitioned data organization (BPAM) , is 
discussed throughout the publication, when 
it is used for program storage. 

A partitioned data set (PDS) is composed 
of named, independent groups of sequential 
data, each of which is called a member. 
Each member has a simple name stored in a 
directory that is part of the data set and 
that contains the location of each member' s 
starting point. Partitioned data sets are 
used to store programs, and are often 
referred to as libraries . 

The full range of facilities available 
in BPAM are not available to the COBOL 
programmer. A partitioned data set may be 
referred to in COBOL only by treating it as 
a standard sequential data set. 



2. A direct data set is one in which 
records are referred to by use of 
relative track addressing. An ACTUAL 
KEY specifies the track relative to 
the first track allocated to the data 
set and identifies the record on the 
track. 



3. A relative data set is one in which 
records are referred to by use of 
relative rec ord addressing. A NOMINAL 
KEY identifies the record location 
relative to the first record in the 
data set. 



4. An indexed data set is one in which 
records are arranged on the tracks of 
a mass storage device so as to permit 
access in logical sequence (according 
to a key that is part of every 
record) . A separate index or set of 
indexes maintained by the system 
indicates the location of each record. 
This permits random, as well as 
sequential, access to any record. 
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T T T T 

| Permissible | 
ACCESS Clause and | Record Formats | 

Organization Field |- T -j Device 

(N) in System-name | Blocked j Unblocked j Requirements 



File Processing 
Requirements 



Write, read, and 
update standard 
sequential file 



+ „_+__„„ 

ACCESS SEQUENTIAL | F, V, S | F, V, U 
or ACCESS clausej j 
is omitted j j 
N=S | | 



| Mass Storage 
| Magnetic Tape 
j Unit Record 



IF 



File 

Processing 

Technique 



QSAM 



Write and read a 
mass storage file 
with relative 
record addressing 



ACCESS SEQUENTIAL | 

or omitted j 

N=R j 



Mass Storage 



BSAM 



Read and update 
a mass storage 
file with relative 
record addressing 



ACCESS RANDOM 
N=R 



Mass Storage 



BDAM 



4- 



Create and read a 
mass storage file 
with relative 
track addressing 



ACCESS SEQUENTIAL | 

or omitted | 

N=D j 



4- 



F, V, U, S | Mass Storage 
I 



BSAM 



Create, read, update, 
and insert into a 
mass storage file 
with relative 
track addressing 



ACCESS RANDOM 
N=D or W( REWRITE) 



F,V, U,S | Mass Storage 



BDAM 



Create a mass 

storage file with 
indexed sequential 
organization 



ACCESS SEQUENTIAL |F 

or omitted j 

N=I j 

I 



IF 



JMass Storage 



QISAM 



Read and update 
a mass storage 
file with indexed 
organization 



ACCESS SEQUENTIAL |F 

or omitted j 

N=I | 

I 



JMass Storage 



QISAM 



Read, update, and 
insert into 
a mass storage 
file with indexed 
random 
organization 



ACCESS RANDOM 
N=I 



IF 



| Mass Storage 



BISAM 



Figure 11. Determining the File Processing Technique 



ACCESSING A STANDARD SEQUENTIAL FILE 



A standard sequential file may only be 
accessed sequentially, i.e., records are 
read or written in the order in which they 
appaar on the file. The file processing 
technique used to create and retrieve a 
standard sequential file is QSAM (Queued 
Sequential Access Method) . Table 7 shows 
the COBOL clauses that may be used with 
these files. Special considerations for 
these clauses are as follows: 

1. The RESERVE clause can be used to 
specify more buffer areas, allowing 
overlap of input/output operations 
with the processing of data. If this 
clause is not used, additional buffers 
may be specified by using the BUFNO 
option in the DD statement. If no 
additional buffer areas are specified, 
two buffers are reserved by the 
system. When the SAME AREA clause is 
specified for the file, the number of 
buffers used is determined from the 
RESERVE clause or if the RESERVE 
clause is not present, it is given a 
default of two. The BUFNO option in 
the DD statement is ignored if the 
SAME AREA clause is specified. 

2. If the WRITE BEFORE/AFTER ADVANCING 
statement or the WRITE AFTER 
POSITIONING statement is used, the 
record size specified in the FD entry 
must allow for the carriage control or 
stacker select character, even though 
the character is not to be printed or 
punched. For example, if the record 
size specified in the FD entry is 121, 
the actual record is 121 characters; 
however, only 120 characters are 
printed or punched. 

No tes ; 

• If the immediate destination of the 
record is a device that does not 
recognize a carriage control or 
stacker select character, the system 
assumes that the control character 
is the first character of the data. 
If the WRITE BEFORE/ AFTER ADVANCING 
statement or the WRITE AFTER 
POSITIONING statement is not used, 
the first byte of the record is 
treated as data by the punch or 
printer. 

• The compiler may direct extra 
records, containing the appropriate 
control characters, to the file to 
effect printer spacing as specified 



in the WRITE BEFORE/ AFTER ADVANCING 
statement. These extra records are 
for spacing purposes only and will 
not appear externally if the file is 
assigned to an online printer. 
However, if the file is assigned to 
a device that does not recognize the 
control characters (for example, a 
tape or a direct-access device), the 
extra records are written onto the 
file. These extra records are 
produced only if ADVANCING more than 
three lines is specified or if both 
the BEFORE and AFTER options are 
specified for a file. 



3. If the input device is the card 
reader, RECORDING MODE IS F should be 
specified. If RECORDING MODE IS V or 
S is specified, the first 8 bytes of 
the record will be interpreted as the 
control bytes required for files with 
format V or S records. 

4. If standard sequential files are on 
magnetic tape, the record block size 
should be at least 18 bytes. Records 
less than 18 bytes in length will be 
read with no problems, unless a parity 
check occurs. If a parity check 
occurs while reading a record less 
than 18 bytes, it will be treated as a 
noise record and skipped over. 

5. The S (standard) option can be 
specified in the DCB RECFM 
subparameter for a fixed/blocked 
record data set with only standard 
blocks (i.e., having no truncated 
blocks or unfilled tracks within the 
data set, except for the last block of 
the last track) . If a fixed/blocked 
data set is created through the use of 
an American National Standard COBOL F 
program, a truncated physical block 
may be written only by the executions 
Of the CLOSE or CLOSE UNIT (or REEL) 
statement. Therefore, on a single 
volume data set, a COBOL-created fixed 
record set is standard except, 
possibly, when the data set is 
extended using DISP=MOD. 

6. The T (TRACK OVERFLOW) option can be 
specified for the DCB RECFM 
subparameter of the DD statement for 
QSAM files With RECORDING MODE V, S, 
or F. Specification of the T option 
is equivalent to including the APPLY 
RECORD- OVERFLOW option in the source 
program, but use of the T option in 
the DD statement allows the user to 
make his selection at object time. 
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Table 7. COBOL Clause for Sequential File Processing 



Data Management 


Device 


Access 


KEY 


OPEN 


Access 


CLOSE 


Techniques 


Type 


Method 


Clauses 


Statement 


Verbs 


Statement 


QSAM 


TAPE 


SEQUENTIAL 


NOT 


INPUT 


READ [INTO] 


[REEL) 








ALLOWED 


("REVERSED"] 
LNO REWINDJ 


AT END 




LOCK 

NO REWIND 














LEAVE 








POSITIONING 














REREAD 








DISP 














DISP 
















OUTPUT 


WRITE [FROM] 














NO REWIND 
LEAVE 




Tl BEFORE) I 
[ADVANCING 

[/after \ J 














REREAD 


















.DISP 




[AFTER POSITIONING] 




QSAM 


MASS 


SEQUENTIAL 


NOT 


INPUT 


READ [INTO] 


[UNIT] 




STORAGE 




ALLOWED 




AT END 


[LOCK] 


OUTPUT 


WRITE [FROM] 












INVALID KEY 














WRITE [FROM] 














[(BEFORE) "1 
[ADVANCING 

[/after 1 J 














[AFTER POSITIONING] 












I-O 


READ [INTO] 

AT END 
WRITE [FROM] 

INVALID KEY 
REWRITE (FROM] 

INVALID KEY 


[LOCK] 



Figures 12 and 13 show the parameters in 
the DD statement that may be used with 
standard sequential files. All parameters 
except the DCB are described in "Job 
Control Procedures." Additional DCB 
subparameters not shown in the illustration 
are required for use with the Sort feature 
(see the chapter "Using the Sort Feature" 
for information on these parameters). 

The DCB subparameters that can be 
specified in the DD statement for standard 
sequential files are as follows: 



DEN={0|1|2|3} 

can be used with magnetic tape, and 
specifies a value for the tape 
recording density in bits per inch as 
listed in Table 8. If no value is 
specified, 800 bits-per-inch is 
assumed for 7-track tape, 800 
bits-per-inch for 9-track tape without 
dual density and 1600 bits-per-inch 
for 9-track tape with dual density. 



DCB=[DEN={0|1|2|3}] 

[,TRTCH={C|E|T|ET}] 

[ # PRTSP={0|1|2|3}] 

[,MODE={C|E>] 

[,STACK={1|2>] 

[,OPTCD={W|C| WC|T|Q| Z}] 

[ # BLKSIZE=integer] 

[,BUFNO=integer] 

[ , EROPT= { ACC | SKP | ABE } ] 

[,RECFM={S|T>] 



Table 
r 



8. 



DEN Values 



T T 

I Tape Recording Density | 
| (Bits per inch) — Model 2400 | 
f. T J, 

DEN Value | 7 Track | 9 Track | 
l + + ., 



200 
556 
800 



800 
1600 



Vb 



TRTCH={C|E|T|ET} 

is used with 7-track tape to specify 
the tape recording technique, as 
follows: 

C - Specifies that the data-conversion 
feature is to be used; if data 
conversion is not available, only 
format F and format U records are 
supported by the control program. 

E - Specifies that even parity is to 
be used; if omitted, odd parity is 
assumed. 

T - Specifies that BCD to EBCDIC 
conversion is required. 

ET- Specifies that even parity is to 
be used and BCD to EBCDIC 
conversion is required. 



OPTCD= {W|C|WC|T|Q|Z} 

requests an optional service provided 
by the system as follows : 

W - To perform a write validity check 
(on mass storage devices only). 

C - To process using the chained 
scheduling method (see the 
publication IBM OS D ata Management 
Services ) . 

WC- To perform a validity check and 
use chained scheduling. 

T - To request user totaling facility. 



Q - To translate to or from ASCII 

Z - To request the search direct 
option 



PRTSP={0|1|2|3} 

specifies the line spacing on a 
printer as 0, 1, 2, or 3. If PRTSP is 
not specified, 1 is assumed. 

The PRTSP subparameter is valid only 
if the unit specified for the file is 
a printer. It is not valid if the 
file is a report file, nor is it valid 
if the WRITE statement with the 
BEFORE/AFTER ADVANCING option or WRITE 
AFTER POSITIONING is specified in the 
COBOL source program. Single spacing 
always is assumed for a printer unless 
other information is supplied. 



If this information is not supplied 
by any source, none of the services 
are provided, except in the case of 
the IBM 2321 mass storage device where 
OPTCD=W is specified by the operating 
system. 

Note: If the validity check is 
specified, the system verifies that 
each record transferred from main 
storage to mass storage is written 
correctly. Standard recovery 
procedures are initiated if an error 
is detected. 



MODE={C|E} 

can be used with a card reader, a card 
punch or a card-read punch 
and specifies the mode of operation 
as follows: 



BLKSI ZE=integer 

is used to specify the block size. 
This clause is used only when BLOCK 
CONTAINS RECORDS was specified at 
compile time. 



C - Specifies card image (column 
binary) mode. 

E - Specifies EBCDIC code. 

If this information is not supplied 
by any source, E is assumed. 



STACK={1|2} 

can be used with a card reader, a card 
punch, or a card- read punch, and it 
specifies which stacker bin is to 
receive the card. Either 1 or 2 is 
specified. If this information is not 
supplied by any source, 1 is assumed. 

STACK should not be used when the 
WRITE statement with the AFTER 
ADVANCING or POSITIONING option is 
used to specify pocket selection. 



BUFNO=number of buffers 

is used to specify the number of 
buffers to be assigned to the file 
when neither the RESERVE nor the SAME 
AREA clause is specified for the file 
in the source program. The maximum 
number is 255. However, the maximum 
number allowed for an installation is 
established when the program product 
is installed. 



EROPT= { ACC | SKP | ABE > 

specifies the options to be executed 
if an error occurs in writing or 
reading a record as follows : 

ACC - To accept the error block for 
processing. 

SKP - To skip the error block. 



User File Processing 77 



ABE - To terminate the job. 

There are two cases when the 
subparameter can be specified: 

• If no error processing declarative 
(USE sentence) is specified, the 
option is taken immediately. 

• If an error processing declarative 
is specified, the option is taken 
after the error declarative returns 
control via a normal exit (and only 
if that is the case) . 



If no option is specified, ABE is 
assumed. 



RECFM={S|T} 

specifies the option to be executed in 
processing the data set, as follows: 



S - to expect the data set to consist 
of standard blocks; this option 
can be specified only if the 
RECORDING MODE is F. 



T - to use the TRACK OVERFLOW option 
(this specification has the same 
effect as including the APPLY 
RECORD- OVERFLOW option in the 
source program) . 



LABEL 



Device Type 



Parameter 


4- 

1 

_L_ 


Mass 


Storage 


T 

1 

X 


Magnetic 


Tape 


T - 

1 

_ _ -L_ 


Unit 


Record 


DSNAME 


T 

1 

4_ 










as 








UNIT 


T 

1 
_L_ 










as 








VOLUME 


T 

1 
+ - 






as 






T~ 

1 
+- 




na 



| SL 
I SUL 



| SL 

| NL 

| NSL 

I SUL 



NL 



SPACE 



as 



na 



SUBALLOC 



SPLIT 



DISP 



\ NEwl (, KEEP ) 

|mod( \pass f 



,KEEP 
I, PASS 
\,CATLG / 

/, delete\ 



| SYSOUT=A, B. 



DCB Device Dependent | OPTCD=W, WC 



TRTCH , DEN 



j PRTSP, MODE, STACK 



DCB General 



| OPTCD=C/T, BUFNO, BLKSIZE, EROPT=ABE 
I RECFM={S|T> 



| EROPT=ACC 
j (printer only) 
| EROPT=ABE 
~L . 



as = Applicable subparameters 
na = Not applicable 



Figure 12. DD Statement Parameters Applicable to Standard Sequential OUTPUT Files 





i 










Device Type 










1 






T" 






T~ 






Parameter 




Mass Storage 


1 


Magnetic Tape 


1 


Unit 


Record 




i 






X. 






_X_ 








1 


















DSNAME 


i 










as 










1 






~T" 






T" 






UNIT 




NOt 


required 




Not 


required 


1 










if 


cataloged 




if cataloged 


1 




as 




i 






4.. 






-4.- 








1 






T 






T 






VOLUME 




Not 


required 




Not 


required 


1 










if 


cataloged 




if cataloged 


1 




na 




l 






J.. 






-4-- 








1 






T 












LABEL 


l 


SL 
SUL 




X- 


SL 
NL 
NSL 
SUL 




1 

i 
1 
I 

_x_ 




na 




l 


















SPACE 


1 










na 










l 


















SUBALLOC 


l 










na 










1 


















SPLIT 


1 










na 










l 








7 


7 T 








DISP 


i 








10LD 

JSHR 


Lkeep / 

\ J, PASS { 
\,CATLG / 
J,UNCATLGl 
[.DELETE J 










1 


















DCB Device Dependent! 




— 


1 


TRTCH, DEN 


1 


MODE, 


STACK 




l 






X. 






x_ 








1 


















DCB General 




OPTCD=C/T, BLKSIZE, 


BUFNO, 


EROPT=ACC, SKP 
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as = Applicable subparameters 
na = Not applicable 



Figure 13. DD Statement Parameters Applicable to Standard Sequential INPUT and 1-0 Files 



SPECIFYING ASCII FILE PROCESSING 



The compiler is notified by a special 
format of the ASSIGN clause that an ASCII 
(American National Standard Code for 
Information Interchange) file is to be 
created or read. The system-name in the 
ASSIGN clause must have the following 
format to indicate that an ASCII file is to 
be processed: 



UT ( -device ) -C- ( buffer offset ) -name 



device 

which if specified must be a magnetic 
device, since ASCII support is only 
for magnetic tape files. If the 
device is omitted here, the magnetic 
tape device may instead be specified 
at execution time through JCL. 



an organization code which specifies 
that an ASCII-encoded sequential file 
is to be processed, or that an 
ASCII-collated sort is to be 
performed. 



where: 



UT 



must be specified for a utility. 



buffer offset 

a two-character field that indicates 
the length of the block prefix for 
that file. This entry is required if 
a non-zero block prefix exists; it 
must, however, be omitted when an 
ASCII-collated sort is requested. 
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a field of 1 to 8 characters that 
specifies the system-recognized name 
of the file. It is this external name 
that appears in the name field of the 
DD card for the file. 



Alternatively, the programmer may omit this 
specification from the ASSIGN clause, 
instead making use of the phrase BLOCK 
CONTAINS RECORDS. The offset can then oe 
specified at execution time in the JCL. 
However, if BLOCK CONTAINS RECORDS is 
used, the following options must be 
included in the JCL: 



PROCESSING ASCII FILES 



Record formats allowed for ASCII files 
are the following: mode F (fixed length), 
mode U (undefined), and mode D (variable 
length). D-roode records are of variable 
length with a four-byte record descriptor 
field for each record. The COBOL 
programmer processing variable-length 
records specifies V-mode records. Then the 
format information generated from the DCB 
parameter is internally converted to D 
mode. Format-D records cannot be 
explicitly specified by the user in a COBOL 
program. 



Block Prefix 



BUFOFF=(n) 

must be included in the DCB parameter 
of the EXEC card, where n is the 
length of the block prefix from to 
99 characters on input, and either 
or 4 on output. 



BLKSIZE=(n) 

must be included on the DD card, where 
n is the size of the block, including 
the length of the block prefix. 



Notes: 



If a block prefix exists on an ASCII 
file and the BLOCK CONTAINS clause with 
the CHARACTERS option is used, the 
length of the block prefix must be 
included in the BLOCK CONTAINS clause. 



An ASCII file may have a variable-length 
field, called a block prefix , preceding the 
first logical record in a physical record. 
If this prefix exists on an ASCII file, its 
length must be indicated at compile time in 
the buffer offset field of the ASSIGN 
clause. The compiler places this length in 
the DCB parameter at compile time. 

Whether the optional block prefix 
contains the block length or simply user 
information depends on the type of file 
specified (input or output) and the 
internal record mode ( i.e. , F, U, or D) . 
These distinctions are made in the 
discussion that follows. 



• If either the RECORDS option is 

specified or the BLOCK CONTAINS clause 
is omitted, the compiler compensates 
for the block prefix (if specified!. 

Additional JCL considerations for ASCII 
data sets follow. 



LABEL= 



where AL specifies American National 
Standard labels, AUL specifies American 
National Standard and user labels, and NL 
indicates no labels. 




F ile s Opene d a s I n put : Input files with 
either blocked or unblocked records have an 
optional block prefix of to 99 bytes that 
does not contain the block length but may 
contain user information. For D-mode 
records, however, a block prefix of length 
four may contain the block length. 
Regardless of the record format, file 
processing is identical to that for files 
coded in EBCDIC. 

F ile s Opened as Output: The block prefix 
for output files applies only to D-mode 
records and, when specified, must have a 
length of 4. The prefix must contain the 
length of the block, which length includes 
the buffer offset. 

For any ASCII output file the ASSIGN 
clause may include a buffer offset of four. 



The subparameters below are specified in 
the DCB parameter of the DD statement: 

OPTCD=Q, where Q specifies an ASCII-encoded 
data set. 

RECFM=D, where D represents a 

variable-length record, is an optional 
parameter. Whether or not this 
parameter is specified at execution 
time, the programmer must specify an 
ASCII file in the ASSIGN clause as 
well as a mode-V record. The compiler 
converts from mode V to mode D, or to 
the internal representation for a 
variable-length record. 

BUFOFF=(L), where L indicates a four-byte 
block prefix that contains the block 
length including the block prefix. 



Rfi 



Hand l ing Numeric Data Items from ASCII 
Files 



It is highly recommended that the 
programmer take advantage of the separately 
signed numeric data type. The SIGN clause 
(see "SIGN Clause" in the chapter 
"Programmer Considerations") can be used to 
specify the position and the mode of 
representation of the operational sign of 
numeric data items. 



• Record Identifier 

The remainder of data-name, which is 1 
through 255 bytes in length, is the 
record identifier. It represents the 
symbolic portion of the key field used 
to identify a particular record on a 
track. 



The following example illustrates the 
use of the ACTUAL KEY clause: 



DIRECT FILE PROCESSING 



The direct file processing technique is 
characterized by the use of the relative 
track addressing scheme. When this 
addressing scheme is used, the tracks of 
mass storage devices are consecutively 
numbered from to n (where equals the 
first track of the file, and n equals the 
last track). The positioning of logical 
records in a file is determined by the 
ACTUAL KEY supplied by the user in the 
Environment Division. The first part of 
the key, called the track identifier, 
specifies either the track on which space 
for the record is first sought or the track 
at which the search for a record is to 
begin. The second part, called the record 
identifier, serves as a unique identifier 
for the record. Files with direct data 
organization must be assigned to mass 
storage devices. 



ENVIRONMENT DIVISION. 



ACTUAL KEY IS THE-ACTUAL-KEY. 



DATA DIVISION. 



WORKING- STORAGE SECTION. 
01 THE-ACTUAL-KEY. 

05 TRACK-IDENT PIC S9(5) COMP SYNC. 

05 RECORD-IDENT PIC X(25). 



Note: The same record identifier may 
appear more than once in the same file when 
using COBOL. However, using the same 
record identifier is not recommended for 
the following reasons: 



r 1 

| Format | 

y .| 

I I 

I ACTUAL KEY IS data-name j 

I I 

L J 



1. If they appear on the same track, only 
the first occurrence can be retrieved 
(using EDAM) . 



Data-name may be any fixed item from 5 
through 259 bytes in length and must be 
defined in the File Section, Working- 
Storage Section, or Linkage Section. The 
following considerations apply when 
defining the ACTUAL KEY: 

• Track Identifier 

The first four bytes of data-name are 
the track identifier. The identifier 
is used to specify the relative track 
address for the record and must be 
defined as a 5-integer binary data item 
whose maximum value does not exceed 
65,535. 



2. If an extended search is used in 

either creating or updating a file, 
the position of records containing 
duplicate record identifiers may be 
unpredictable. 



With direct file processing, records 
must be unblocked and may be V-, U-, F-, 
S-mode records. Figure 14 illustrates 
those parts of a directly organized file 
that are of importance to a COBOL 
programmer. 



or 
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INDEX 

POINT GAP 
I I 



RO 



Rl 



R2 



I r ., r n r T T 1 f T T 1 

V | TRACK | | CAPACITY! j I I I i ill 

G | ADDRESS | G | RECORD I G | COUNT \ KEY j DATA \ G | COUNT | KEY ! DATA | G 

L J L J L i ± J L X JL J 



Figure 14. Directly Organized Data as it Appears on a Mass Storage Device 



Each track contains the following: 



Index Point 

There is one index point to indicate 
the physical beginning of each track. 



(G aps) 

Gaps separate the different areas on 
the track. Certain equipment 
functions take place as the gap is 
rotating past the read/write head. 
The length of the gap varies with the 
device, the location of the gap, and 
the length of the preceding area. For 
instance, the gap that follows the 
index point is a different length than 
the gap that follows the track 
address. The length of the gap that 
follows a record depends on the length 
of that record. 



Track Address 

This field defines the physical 
location of the track. It indicates 
the cylinder in which the track is 
located and the read/write head that 
services the track. 



R O ( Capacit y Record) 

This field indicates the amount of 
unused space available for additional 
records on the track. 



Rl, R2, ..., Rn 

These are physical records that 
contain the following: 

count area — control information 



key area — 



data area -- 



the-record identifier 
(1-255 bytes) as 
specified by the 
programmer in the ACTUAL 
KEY clause. 



the-data moved into the 
FD before a WRITE 
statement was executed. 



The following example illustrates the 
relationship between the ACTUAL KEY and the 
positioning of records on a mass storage 
device during the creation of a direct 
file. 



ENVIRONMENT DIVISION. 



ACTUAL KEY IS THE-ACTUAL-KEY. 



DATA DIVISION. 
FILE SECTION. 
FD DIRECT- FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1 PIC X(200). 



WORKING- STORAGE SECTION. 
01 THE-ACTUAL-KEY. 

05 TRACK-IDENT PIC S9(5) COMP SYNC. 

05 RECORD-IDENT PIC X(3). 
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TRACK 



Count Key Data 



Count Key Data 



r t t 1 r- 

| |AAA|REC-1| G | 
L J. J. J L. 



"T t 1 r - 

|CCC|REC-1| G | 
.X X J L. 



Count Key Data 

— T T 1 

|BBB|REC-1| 
-_X X J 



TRACK 1 



r t t 1 i" 

| |DDD|REC-1| G | 
L X X J L. 



t t 1 r - 

|FFF|REC-1| G | 
.X X J L. 



T T 1 

|EEE|REC-1| 
-X X J 



t J 

Figure 15. Sample Format of the First Two Tracks of a Direct File 



Consider REC-1 being written six times; the 
contents of THE-ACTUAL-KEY varying with 
each WRITE instruction: 



THE-ACTUAL-KEY 

TRACK | RECORD 
IDENT|IDENT 

r 4 1 

WRITE 1 I | AAA| 

h — + — ^ 

WRITE 2 | | CCC| 
j. 4 .| 

WRITE 3 | | BBB| 

h — + — ^ 

WRITE 4 j 1 j DDD| 

I" + 1 

WRITE 5 | 1 | FFF| 

h 4 1 

WRITE 6 | 1 | EEE| 
L X J 



Relative track and relative track 1 
the mass storage device will appear as 
shown in Figure 15. 



of 



When the WRITE statement is executed, 
the system seeks the track that corresponds 
to the number contained in TRACK-IDENT. It 
then searches for the next available 
position into which a record may be placed. 
The system writes a count area, writes the 
contents of RECORD-IDENT in the key area, 
and writes the information contained in 
REC-1 in the data area. 



N ote : The record identifier is not 
included in the level-01 record description 
(REC-1). It will, however, be moved into 
the output buffer before being written on 
the mass storage device. Buffer areas, 
therefore, will be large enough to 
accommodate both the contents of REC-1 and 
the record identifier. 



Dummy and Capacity Records 



Once a direct file has been created, 
records can be added randomly on tracks 
formatted sequentially. Unless a track is 
already filled with data records, it is 
formatted by the compiler via the writing 
of dummy records (mode F) or of one 
capacity record (mode U, V, or S). 



In order to format tracks, a COBOL 
subroutine executes instructions to write 
dummy records for F-mode files or write 
capacity records for V-, U-, or S-mode 
files. Dummy records are identified by the 
presence of the figurative constant 
HIGH-VALUE in the first oyte of the record 
identifier portion of the ACTUAL KEY. This 
indicates to the system that a record can 
be added to the file in the space assigned 
to the dummy record. (The user should not 
attempt to retrieve a dummy record by 
moving this configuration to the record 
identifier because it is considered an 
invalid key. ) A capacity record is a 
single record at the physical beginning of 
each track that indicates the amount of 
space available for additional records. As 
V-, U-, or S-mode records are added to a 
track, the capacity record is written 
accordingly. Capacity records are never 
made available to the user. 



When a file is created, it should 
contain enough dummy records, or 
appropriately written capacity records, to 
allow for future expansion. Once the file 
is closed, more space cannot be allocated 
and the extent of the file cannot be 
increased. 



Note: Tracks that have been assigned to a 
file but are not formatted, are considered 
"allocated. " The user should not attempt 
to write on tracks that have been allocated 
but not formatted. 
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S eq uential Creation of Direct Data Set 



The file processing technique used to 
create a direct file sequentially is BSAM 
(Basic Sequential Access Method). 

• The associated COBOL statements are 
summarized in Table 13. 

• The associated JCL parameters are 
summarized in Table 14. 



The ACTUAL KEY is required. It 
specifies the relative track number on 
which the record is to be written. Since 
access is sequential, all records will be 
written serially in the sequence in which 
they are moved into the output buffer. It 
is, therefore, necessary that all records 
to be written on the first track (track 
identifier = 0) be processed before records 
to be written on the 2nd, 3rd, . . . , nth 
track (track identifier = 1, 2, ..., n-1) 
are processed. 

When records are written sequentially, 
the user need not update the contents of 
the track identifier portion of the ACTUAL 
KEY. A COBOL subroutine will update it as 
follows: 

• Records will be written on the first 
available track until space is no 
longer available. At such time, the 
COBOL subroutine will increment the 
track identifier by 1, and continue 
writing on the next track. 

• The value of track identifier used by 
the system is made available to the 
user in the track identifier portion of 
the ACTUAL KEY after the record is 
written. 

• After a CLOSE or CLOSE UNIT statement 
has been executed, the COBOL subroutine 
places the relative track number of the 
last track written on (for a data, 
dummy, or capacity record) in the track 
identifier of the ACTUAL KEY. 

• If the user updates the contents of 
track identifier and attempts to write 
on track 2 when tracks through 4 are 
already full, the system will 
automatically adjust the track 
identifier to 5 (the next track with 
available space). 



If the user wishes to skip tracks, the 
number of tracks, equal to the number of 
tracks to be advanced, must be added to the 
track identifier. The COBOL subroutine 
will then add dummy records (F-mode) or 
write capacity records (V-, U-, or S-mode) 



to complete the intervening track (s) (see 
"Dummy and Capacity Records"). If the 
value of track identifier for the initial 
WRITE is not 0, the subroutine will 
complete the preceding tracks with dummy or 
capacity records. 



SPACE ALLOCATION FOR SINGLE VOLUME FIL ES : 
When a file is created sequentially, the 
number of primary tracks specified on the 
DD card must be available on the primary 
volume. If this quantity is not available, 
the job will not begin execution. Once 
execution begins however, the final 
allocation of space will not be made until 
the file is closed. 



The following discussion illustrates the 
space allocated to a direct file created 
using BSAM. Figure 16 is an example of a 
user program that: 



• Writes 350-1/2 tracks and then closes 
the file. 

• Specifies SPACE=(TRK, (200, 100) ) on the 
associated DD card. 

TRA C K-LIMIT Clause Specified : 

1. If the TRACK-LIMIT clause specifies 
TRACK-LIMIT = 500 and the file is 
closed after writing only 350-1/2 
tracks : 

Note: A COBOL subroutine will format 
all remaining tracks up to and 
including the 500th track. This 
represents 150 extra tracks on which 
records may be added. 

2. If the TRACK-LIMIT clause specifies 
TRACK- LIMIT = 300 and the program 
continues writing all 350-1/2 tracks: 

Note: The TRACK-LIMIT clause is 
ignored and the system allocates and 
formats as if no TRACK-LIMIT clause 
had been specified. 



TRAC K-LIMIT Clause Not Specified : If the 
TRACK-LIMIT clause is not specified, the 
system will allocate the primary extent 
(i.e., 200 tracks) and up to 16 secondary 
extents (i.e., 100 tracks each), as 
required. In Figure 16, the system 
allocates the first 200 tracks, all of 
which are completed. The second 
allocation, of 100 tracks, is also 
completed. The next 100-track allocation 
is, however, only partially used. The file 
is closed after writing on 350-1/2 tracks. 
At this time: 



• A COBOL subroutine will format the rest Note: In some of the foregoing cases, the 



of the 351st track. (Note that 351 
tracks are actually relative tracks 
through 350) 

• The balance of 4 9 tracks will remain 
allocated but will not be formatted. 



number of tracks allocated to the file 
exceeds the number of tracks formatted by 
the COBOL subroutine. If the excess space 
was requested in track or block units, it 
should be released by specifying the RLSE 
option of the SPACE parameter. 



Specified as TRACK-LIMIT=500 



TRACK-LIMIT Clause Not Specified 



+ -I 



written on 
formatted 



formatted 




fist allocation 



2nd allocation 



3rd allocation 



4th allocation 



written on ]| 
and/or /|- 



formatted 



unformatted < | 



200 



1 



\- 



51 
49 



it 



allocation! 



If 
100 \\ 2nd allocationl 
j. ^ 



I 



I- 

i i 

| unused | 



3rd allocationl 



j. x .j 

No tes : 

1. SPACE=(TRK, (200,100) ) on a single volume. 

2. The user program writes 350-1/2 tracks before closing the file. 

l J 

Figure 16. Sample Space Allocation for Sequentially Created Direct Files 
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Specified as 
TRACK-LIMIT=950 




formatted 



| 100 
j. -J 

| 100 

h 1 

I 

| 100 

h 1 

I 

L j 



formatted 



C 

50 

50 



\ 

I 

unused | 



formatted 
allocated 



,.__ H 



A 
r V 



TRACK-LIMIT 
clause not 
specified 



300 



I- 1 



unused I 



formatted 



100 
h j 

unused! 



formatted 



100 
j. ^ 

unused 



formatted 



J. ^ 

| SPACE=(TRK # (300,100)) on Volumes A, B # and C | 

L J 

Figure 17. Sample Space Allocation for Randomly Created Direct Files 



Random Creation of a Direct Data Set 



The file processing technique used to 
create a direct file randomly is BDAM 
(Basic Direct Access Method). 



• The associated COBOL statements are 
summarized in Table 13* 



• The associated JCL parameters are 
summarized in Table 14. 



Figure 18 (sample program) illustrates 
the random creation of a direct data set. 



The ACTUAL KEY is required. When a 
direct file is created randomly, records 
need not be written in any particular 
sequence. The system seeks the track 



specified in the track identifier portion 
of the ACTUAL KEY and writes the record in 
the next available position on that track. 



When a file is created using BDAM, the 
number of tracks specified in the primary 
extent must be available on the primary 
volume. If there are secondary volumes, 
one secondary extent must be available on 
each of the secondary volumes. If these 
extents are not available, the job will not 
begin execution. Once execution begins, 
the final allocation of space is determined 
by the TRACK-LIMIT clause and the SPACE and 
volume-count parameters of the DD card when 
the file is opened as an output file. 
Figure 17 illustrates the allocation and 
formatting of space when the TRACK-LIMIT 
clause is specified as well as when it is 
not specified (see "Dummy and Capacity 
Records" for a definition of allocate and 
format) . 



a* 



1. When a TRACK-LIMIT clause is specifed 
(Figure 17), the system will do the 
following: 

a. Allocate tracks, by blocks, until 
the quantity specified by the 
TRACK-LIMIT clause has been 
equaled or just exceeded. 

b. Format only the space specified in 
the TRACK-LIMIT clause, even if 
the space formatted is less than 
the space allocated. 

2. When a TRACK-LIMIT clause is not 
specified (Figure 17), the first 
volume will be allocated and formatted 
according to the primary allocation 
quantity, and any succeeding volumes 
will be allocated and formatted from 
the secondary quantity, one quantity 
per volume. 



Records cannot be written on those 
tracks that were allocated but unformatted. 
Any attempt to do so will have 
unpredictable results. Unformatted tracks 
can be released by specifying the RLSE 
option in the SPACE parameter on the 
corresponding DD statement. Only space 
requested in track or block units can be 
released. if the CYL subparameter was 
specified, the unformatted tracks cannot be 
released. 



corresponds exactly to the physical 
sequence of the records on the mass storage 
device. Dummy records, if present, are 
also made available. 

For reading a file sequentially, the 
ACTUAL KEY clause need not be specified; 
however: 

• If the key is not specified, the user 
will have no way of distinguishing 
between real and dummy records (F-mode 
only). Dummy records can be recognized 
bv testing for the presence of the 
figurative constant "HIGH VALUE" in the 
first position of the record 
identifier. 

• If the ACTUAL KEY clause is specified, 
the record's key will be placed in the 
record identifier portion of the ACTUAL 
KEY during the execution of a READ 
statement. The track identifier, 
however, remains unchanged. 



Random Reading, U pdating, and Addin g to 

Direct Data Sets 



The file processing technique used to 
read, update, and add to a direct file 
randomly is BDAM (Basic Direct Access 
Method) . 



Unlike direct files created with BSAM, 
the BDAM processing technique allocates and 
formats tracks when the file is opened. 
This is significant because the system will 
not allocate secondary extents if the user 
attempts to write on more tracks than the 
quantity initially formatted. 

Note: The extended search option may be 
used during random creation. See "Random 
Reading, Updating, and Adding to Direct 
Data Sets" for a detailed description. 



Seque ntial Reading of Direct Data Se ts 



The file processing technique used to 
read a direct file sequentially is BSAM 
(Basic Sequential Access Method). 

• The associated COBOL statements are 
summarized in Table 13. 

• The associated JCL parameters are 
summarized in Table 14. 



When a direct file is being read 
sequentially, records are retrieved in 
logical sequence. This logical sequence 



• The associated COBOL statements are 
summarized in Table 13. 

• The associated JCL parameters are 
summarized in Table 14. 

When records are being retrieved from a 
direct file randomly, the ACTUAL KEY is 
required to determine the track and to 
locate a particular record on that track. 
When a match is found, the data portion of 
the record is read. For an add operation, 
after locating the track, the system 
searches for the next available position on 
the track, and writes the new record. For 
an update operation, after locating the 
track, the system searches for the record 
specified in the record identifier portion 
of the ACTUAL KEY. 

In all of the foregoing cases, the 
specified track is the only one searched. 
If the desired record cannot be found, or 
room for an additional record cannot be 
found, the search terminates with an 
INVALID KEY condition. If the user wishes 
to extend the search to a specific number 
of tracks or to the entire file, the DC3 
OPTCD and LIMCT subparameters should be 
specified on the corresponding DD card. 
(Figure 18 illustrates the use of extended 
search. ) 
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Multivolume Data Sets 



Multivolume data sets, like 
single-volume data sets, may be created 
either randomly or sequentially. 

Sequential Creatio n: When a file is 
created sequentially, the number of tracks 
specified in the primary extent must be 
available on the primary volume and the 
number of tracks specified in the secondary 
extent must be available on each of the 
secondary volumes. If extents are not 
available, execution of the job will not 
begin. Once execution begins, the primary, 
and as many secondary allocations as 
possible, are given to the first volume (up 
to 16 extents per volume). Subsequent 
volumes are allocated from the secondary 
specification. 

If the CLOSE UNIT statement is executed, 
the current extent is formatted, volume 
switching procedures are executed, and the 
contents of ACTUAL KEY are updated to 
reflect the relative track number of the 
last track on the old volume. This is 
illustrated in the following example. 

Consider the creation of a multivolume 
file whose space is allocated by: 

SPACE=(TRK, (300, 100)) 

1. When execution begins, the system 
allocates 300 tracks on the first 
volume. When the 300 tracks are used 
up, the system allocates 100 tracks 
more. Up to 16 allocations of 100 
tracks each are possible. 

2. If, after writing on 450 tracks, a 
CLOSE UNIT statement is executed, a 
COBOL subroutine will format the 
remaining 50 tracks of the current 
allocation before making the next unit 
available. 

3. After the CLOSE UNIT statement is 
executed, a COBOL subroutine places 
the relative track number of the last 
track written on (for a data, dummy, 
or capacity record) in the track 
identifier of the ACTUAL KEY. 

N ote : A CLOSE UNIT statement always 
formats the tracks remaining on that unit 
from the current allocation. The 
formatting of tracks on the last unit, when 
a CLOSE file-name statement is executed, 
depends on the presence or absence of a 
TRACK-LIMIT clause, just as it did for 
single-volume files (see "Space Allocated 
for Single- Volume Files"). The RLSE 
option of the SPACE parameter applies only 
to the unformatted tracks at the end of the 
last unit. 



Automatic Volume Switching : The user may 
choose to permit volume switching to occur 
automatically. This can be accomplished by 
writing on all allocated tracks until no 
more are available, or may be made 
available. This procedure, however, does 
not guarantee a specific distribution of 
records over the volumes, the placement of 
a particular record on a particular volume, 
or whether the data set is, in fact, 
multivolume. 

Note : If the user permits system 
controlled volume switching, but specifies 
the file be created on more than one volume 
[e.g., V0L=SER=(V1,V2, V3) ] ; the system may 
write the entire file on the primary volume 
if there is enough room. The next time an 
attempt is made to open that file, since 
the system expects it to reside on three 
volumes, an ABEND will occur. This can be 
avoided by specifying: 

VOL=(, , ,3,SER=(V1, V2,V3)) 

This specifies the file be contained on one 
or more volumes. 



To create a file with records 
distributed as evenly as posible over 
several volumes, the programmer must 
calculate the amount of space his file will 
require (see "Determination of File Space") 
and divide by the number of volumes. The 
result of this calculation (rounded) should 
be specified as both the primary and 
secondary allocation of the SPACE parameter 
of the associated DD statement. The 
programmer should execute CLOSE UNIT before 
the end of the initially allocated space on 
the first volume (that is, execute the 
CLOSE UNIT before writing the record that 
is to be first on the second volume). 



For example, to distribute 2232 80-byte 
records as evenly as posible on three 2311 
volumes, 34 tracks per volume are required 
and the SPACE parameter should specify 
(34,34). After writing the 744th record 
the programmer should execute CLOSE UNIT 
and continue writing. 

If the required space is overestimated 
and the records do not fill the last 
track(s), the compiler will write dummy 
records to complete them. These records 
are included in the record count and should 
be taken into account when trying to 
address records on subsequent volumes. 

If the space required is underestimated, 
automatic volume switching may occur before 
the CLOSE UNIT is executed since space on 
the first volume is filled. If this has 
happened, the CLOSE UNIT starts a third 
volume. 
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If no secondary allocation has been 
specified and the program issues a CLOSE 
UNIT statement, the job will terminate 
abnormally, since the allocation of 
subsequent volumes is taken from the 
secondary allocation field of the SPACE 
parameter. 

In the creation of an output file, 
performance is improved by specifying the 
CONTIG subparameter of the SPACE parameter 
in the DD statement. However, space 
allocation is more efficient if CONTIG is 
not specified. 



File Organization Field of the System-Name 



The single character "D" or "W" r 
specifying the file organization, must be 
coded as part of the system-name. The user 
should be aware of the following 
differences: 



• Sequentially accessed files must specify 
organization "D". 



Rand om Creation : When a file is created 
randomly, space allocation and formatting 
is done as described in "Random Creation of 
a Direct Data Set" (Figure 17). It is 
important to note that a CLOSE UNIT 
statement is not permitted when creating a 
file randomly. 



The following description pertains to 
Figure 17: 

1. When the TRACK-LIMIT clause is 

specified, the total extent of the 
file is 950 tracks. The only valid 
track identifiers are through 949: 

• Tracks 000 through 499 are contained 
on volume A. 

• Tracks 500 through 899 are contained 
on volume B. 

• Tracks 900 through 949 are contained 
on volume C. 



Randomly accessed files may specify "D" 
or "W". When opened input or output "D" 
and "W" function identically. 



1. Opened output ("D" and n W n ): 

WRITE adds a new record. If a 
record containing the same key 
already exists, the system will add 
the record anyway. The result will 
be records with duplicate keys. 



2. Opened 1-0 <"W") : 

a. REWRITE automatically searches 
for a record with a matching 
record identifier, and updates 
it. 

b. WRITE adds a new record to the 
file whether or not a duplicate 
key already exists. 



2. When the TRACK-LIMIT clause is not 
specified, the total extent of the 
file is 500 tracks. The only valid 
track identifiers are through 499: 

• Tracks 000 through 299 are contained 
on volume A. 

• Tracks 300 through 399 are contained 
on volume B. 

« Tracks 400 through 499 are contained 
on volume C. 



Opened 1-0 ("D") : 

a. WRITE updates the file only if 
the preceding input/output 
statement was a READ of the same 
record. 

b. WRITE adds a new record to the 
file, whether or not a duplicate 
key already exists, if the 
preceding input/output statement 
was anything other than a READ 
of the same record. 
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N ote : When a file is opened 1-0 (BDAM 
"D") the contents of ACTUAL KEY are 
moved to a save area during the 
execution of a READ statement. During 
the execution of a WRITE statement, the 
contents of ACTUAL KEY are compared to 
the contents of the save area to 
determine whether the system should add 
or update a record. A check is also 
made to assure that the preceding 
input/output statement was a READ. If 
it was a WRITE of any record, a new 
record is added to the file. Opening a 
file 1-0 (BDAM "W") omits the save and 
compare steps entirely. The system adds 
a record when a WRITE statement is 
executed and updates a record when a 
REWRITE statement is executed. It is, 
therefore, more efficient to use BDAM 
"W" than it is to use BDAM "D" if it is 
known in advance whether the record 
should be added or updated. 



Determination of File S pace : To determine 
the amount of space a data set requires, 
the following variables should be 
considered: 



Device Type 
Track Capacity 
Tracks per Volume 
Cylinders per Volume 
Data length (block size) 
Key Length 
Device Overhead 



Device overhead refers to the space 
required on each track for hardware data, 
i.e., address markers, count areas, 
inter-record gaps, Record 0, etc. Device 
overhead varies with each device and also 
depends on whether the blocks are written 
with keys. The formulas in Table 9 may be 
used to compute the actual space required 
for each block, including device overhead. 

Table 10 lists device storage capacity, 
and Table 11 lists capacity in records per 
track for several mass storage devices. 

Programmers who require more detailed 
information on mass storage devices may 
refer to the publications that follow: 

I BM OS Compone nt - D escripti on — 2841 
St orage Contro l; 2 3 02 Disk S torage, 
M odels 3 and 4 ; 2311 Disk S torage Drive, 
M odel 7; 2321 Data Call Drive; 2303 
D rum; Order No. A26-5988. 

C omponen t Summ ary -- 2 835 Storage 
Control, 2305 Fixed Head Storage, Order 
No. GA26-1589. 



Comp onent S ummary -- 38 30 Storag e 

Co ntrol , 3330 Dis k Storag e, Order 

No. GA26-1592. 



Note: Specification of the "S" option in 
the DCB subparameter RECFM can markedly 
increase 3330 performance (see the 
description of RECFM earlier in this 
chapter) . 



Rando mizing Techniques 



One method of determining the value of 
the track identifier portion of the ACTUAL 
KEY is called indirect addressing. 
Indirect addressing generally is used when 
the range of keys for a file includes a 
high percentage of unused values. For 
example, employee numbers may range from 
000001 to 009999, but only 3000 of the 
possible 9999 numbers are currently 
assigned. Indirect addressing can also be 
used with nonnumeric keys. A nonnumeric 
field (e.g., alphanumeric), when moved to c 
computational field, will be packed and 
then converted to binary notation. Since 
packing eliminates the zone fields, the 
final binary item will be numeric. 



Indirect addressing means that the key 
is converted to a value for the track 
identifier by use of some algorithm 
intended to limit the range of addresses. 
Such an algorithm is called a randomizing^ 
technique . Randomizing techniques need not 
produce a unique address for every record; 
in fact, such techniques usually produce 
syn onyms. Synonyms are records whose keys 
randomize to the same address. 

Two objectives must be considered in 
selecting a randomizing technique: 

1. Every possible key in the file must 
randomize to an address within the 
designated range. 

2. The addresses should be distributed 
evenly across the range so that there 
are as few synonyms as possible. 



Note that one way to minimize synonyms 
is to allocate more space for the file than 
is actually required to hold all the 
records. For example, the percentage of 
locations actually used might comprise only 
80 to 85 percent of the allotted space. 



Division/Remainder Method : One of the 
simplest ways to address a directly 
organized file indirectly is to use the 
division/remainder method. 

1. Determine the amount of locations 
required to contain the data file. 
Include a packing factor for 
additional space to eliminate 
synonyms. The packing factor should 
be approximately 20 percent of the 
total space allotted to contain the 
data file. 

2. Select the nearest prime number that 
is less than the total of step 1. A 
prime number is a number divisible 
only by itself and the integer 1. 
Table 12 is a partial list of prime 
numbers . 

3. Clear any zones from the key that is 
to be used to calculate the track 
identifier of actual key. This can be 
accomplished by moving the key to a 
field described as COMPUTATIONAL. 



corresponding to part number 25DF3514. The 
record address can be determined from the 
relative location as follows: 

1. Determine the number of records that 
can be stored on a track (e.g., 12 per 
track on a 2311, assuming each 
inventory record is 200-bytes long). 

Note: Because each data record has 
nondata components, such as a count 
area and inter-record gaps, track 
capacity for data storage will vary 
with record length. As the number of 
separate records on a track increases, 
inter-record gaps occupy additional 
byte positions so that data capacity 
is reduced. Track capacity formulas 
provide the means to determine total 
byte requirements for records of 
various sizes on a track (see Tables 
9, 10, and 11). 

2. Divide the relative number (2445) by 
the number of records to be stored on 
each track. 



4. Divide the key by the prime number 
selected. 

5. Ignore the quotient; utilize the 
remainder as the relative location 
within the data file. 



For example, assume that a company is 
planning to create an inventory file on a 
2311 disk storage device. There are 8, 000 
different inventory parts, each identified 
by an 8-character part number. Using a 20 
percent packing factor, 10, 000 record 
positions are allocated to store the data 
file. 



The result, quotient = 203, now 
becomes the track identifier of the 
actual key. 



Method B: Utilizing the same example, 
another approach will also provide the 
relative track address. Method B is 
illustrated in Figure 17: 

1. The number of records that may be 
contained on one track is 12. 
Therefore, if 10, 000 record locations 
are to be provided, 834 tracks must be 
reserved. 



Method A: The closest prime number to 
10,000, but under 10,000, is 9973. Using 
one inventory part number as an example, in 
this case #25DF3514, and clearing the 
zones, we have 25463514. Dividing by 9973 
a quotient of 2553 results in a remainder 
of 2445. Thus, 2445 is the relative 
location of the record within the data file 



2. The prime number nearest, but less 
than 834, is 829. 

3. Divide the zone-stripped key by the 
prime value. (In the example, 
25463514 divided by 829 provides a 
quotient of 30715 and a remainder of 
779. The remainder is the track 
identifier. ) 
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Table 10. Mass Storage Device Capacities 
r t t t — 



T 1 

Total 
Capacity 



Device 
Type 



Volume 
Type 



Track 
Capacity 



Tracks per Cylinder 



Number of 
Cylinders 



2311 

2314(2319) 

2302 

2303 

2301 

2321 

2305-1 

2305-2 

3330 



Disk 
Disk 
Disk 
Drum 
Drum 
Cell 
Drum 
Drum 
Disk 



3625 

7294 

4984 

4892 

20483 

2000 

14136 

14660 

13030 



10 
20 
46 
10 
8 
20*** 



19 



200 
200 
246 

80 

25** 
980*** 

48 

96 
404 



7,250,000 
29,176,000 
56,398,944 

3,913,600 

4,096,600 
39,200, 000 

5,428,224 

11,258, 880 

101,751,270 



♦Capacity indicated in bytes. 
♦♦There are 25 logical cylinders in a 2301 Drum. 
***A volume is equal to one bin in a 2321 Data Cell. 
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Figure 18 is a sample COBOL program that 
creates a direct file using method B (see 
"Randomizing Technigue" ) and provides for 
the possibility of synonym overflow. 
Synonym overflow will occur if a record 
randomizes to a track that is already full. 
The following discussion highlights some 
basic features. Circled numbers in the 
program example refer to corresponding 
numbers in the text that follows. 

1. Since this randomizing technique (jl) 
employs the prime number 829 as its 
divisor, the largest possible 
remainder is 828. By the interaction 
between the TRACK-LIMIT clause f2J and 
the SPACE parameter (^3J , the program 
formats 830 tracks (i.e., relative 
tracks 000-829). This establishes 
track 829 as the only track that can 
contain synonym overflow from track 
828. 

2. The DCB subparameter Qn OPTCD=E is 
specified. If a synonym overflow 
condition arises, an extended search 
will be employed, and the additional 
record will be written in the first 
available position on the following 
track(s) . 



3. The DCB subparameter Q5) LIMCI-5 is 
specified. This limits the extended 
search to five tracks. If no room is 
found within this limit, an invalid 
key condition results. A value should 
always be specified for the LIMCT 
subparameter when OPTCD=E is 
indicated. Otherwise, the default 
value of LIMCT, which is zero, will 
result in an error that will be 
treated as an exceptional input/output 
condition. 

Note: The randomizing technique chosen 
should minimize the number of synonym 
overflows for two reasons : 

1. The more extended search is employed 
during file creation, the more it will 
be required during record retrieval. 
Extended searches increase access time 
proportionately. 

2. When an extended search is employed, 
the adjusted value of the track 
identifier is not made available to 
the user after the execution of a 
WRITE statement. The user, tnerefore, 
has no way of knowing the track on 
which an overflow record is actually 
written. 
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00001 00101 IDENTIFICATION DIVISION. 

00002 00102 FFOGRAH-ID. METHOD B. 

00003 00103 ENVIRONMENT DIVISION. 
00O0U 00104 CONFIGURATION SECTION. 

00005 00105 SOURCE-COMPUTER. IBM-360. 

00006 00106 OBJECT-COMPOTE*. TBM-360. 

00007 00107 TNPnT-OUTPOT SECTION. 

00008 00108 FILE-CONTROL. 

00009 00109 SELECT D-EILE ASSIGN DA-2314-D-N ASTER 
C0010 00110 ACCESS IS RANDOM ACTOAL KEY IS ACT-KEY -^^ 

00011 00112 TRACK-LTMTT IS 830. -« (2) 

00012 **0C103 SELECT C-FTLF ASSIGN UT-S-CARDS. v -^ / 
10013 00114 DATA DIVISION. 

00014 00115 FILE SECTION. 

0001? 00116 FD D-FTLR 

00016 00117 LABEL RECORDS ARE STANDARD. 

00017 00118 01 D-REC. 

00018 00119 02 PART-NOM PTC Y (B) . 

00019 00120 02 NMM-CN-HAND PIC 9 f4) . 

00020 00121 02 PRICE PTC 9(5) V99. 

00021 00122 02 FILTER PTC X(181). 
0^022 00201 FD C-FTLE 

00023 0020? T.ARFL RECORDS APE OMITTED. 

^0024 002C3 01 C-REC. 

10025 C02CU 02 PAET-NOM PTC Y (8) . 

0002* 00205 02 NOM-ON-HAND PIC 9(a). 

00C27 00206 02 PRICE PIC 9(5) V99. 
0C02° 02 'TLIER PJC X(61). 

00029 002C7 WORKING-STORAGE SECTON. 

00030 002C9 77 SAVE PIC ?9 (8) COMP SYVC. 
000H 00210 77 QUOTIENT n TC S9 CM CCMP SYNC. 
00032 00211 01 ACT-KEY. 

0003"» 00212 02 TRACK-ID PTC S9 (5) COMP SYNC. 

00014 00213 02 PEC-ID PTC *(fl). 

000"«5 00214 PROCEDUP" DTVTSTON. 

00016 OPEN TVP'IT C-FTLE OHTPUT D-FTT.E. 

00^7 001C1 RFADS. 

00038 00104 °EAD C- r TLE AT FVD SO TO EOJ. 

100.39 001C5 MOVE <~opt>FSPONDI NS C-PEO TC D-PEC. 

^0040 00106 MOVE PART-NUM OF C-RFC TO REC-TD SAVF. ^-v 

00041 00107 1TVTTE SAV PY 8">9 GIVING Ot'OTTFNT REMAINDER T"> ACT-TD. „ MJ 

00042 001C8 WRITES. ^^^ 
01043 0C1O9 EXHTRTT NAM"i TRACK-!" C-REC. 

onouu 0C310 wpi^e r-i^c tnvalid key no to tnvalid-key. 

00045 0C11 GO T " " P ^S. 

00046 00312 INVALID-KFv. 

00047 00313 DISPLAY 'INVALID KEY • TRACK-IP PEC-TD. 
CC048 0031H FOJ. 

00049 00H5 CLOSE O-FIL 17 D-FTT.E. 

C0050 00316 STOP RUW. 

Figure 18. Sample Program for a Randomly Created Direct File (Part 1 of 



2) 



STEP STEP2 TERMINATED. TIflE 00.00 HR.HDSTH/HR * 00.00.23.30 HP. MIN.SEC. HDPTH/SEC*DATE 70.139 

//STEP3 EXEC PGW=*.STEP2.SYSLMCD 

//SYS00T DD SYS0UT=G ._. 

//SYSUDTJMP DD SYS0UT=A ^^-(3 J 

//1ASTER DD SPACE=(TRK, (500,100) ,RLSE) , ^-^ X 

// DCB= (0PTCD=E,LIMCT=5) , 0NIT=2314 



//CAPES DD * 
// 



V ND 



TPACK-ID = 00801 C-REC = 82900801CD1 

TPACK-ID = 00801 C-REC = 82900801CD2 

TPACK-ID = 00801 C-PEC = 82900801CD3 

^RACir-TD = 00801 C-REC = 82900801CD4 

TRACK-IC = 00031 C-REC = 82900031 

TRACK-ID = 00801 C-REC = 82900801CD5 

TPACK-TD = 00801 C-REC - 82900801CD6 

TPACK-TD = 00801 C-PEC = 82900801CD7 

TPACK-TD = 00801 C-PEC = 82900801CD8 

TPACK-ID = 00801 C-RFC = 82900801CD9 

TRACK-ID = 00801 C-REC = 82900801CD10 

TRACK-ID = 00801 C-REC = 32900801CD11 

TPACK-ID = 00801 C-PEC = 82900801CD12 

TRACK-ID = 00801 C-REC = 82900R01CD13 

TPACK-ID = 00801 C-REC = r '-82900801CD14 

^PACK-TD = 00801 C-PEC = 82900801CP15 

T*ACK-ID = 00801 C-RFC = 82900801CD16 

TRACK-ID = 00000 C-PEC = 829000003 

TPACK-ID = 00801 C-PEC = 82900R01CD17 

TRACK-ID = 00801 C-PEC - 82900801CD18 

TRACK-ID = 00801 C-REC = 82900801CD19 

TRACK-ID = 00801 C-PEC = 82900801CD20 

TRACK-TD = 00809 C-REC = 82900809 

TPACK-TD = 00801 C-REC = 82900801CD21 

TRACK-ID = 00801 C-REC = 829CC801CP22 

TRACK-IE = 00801 C-REC = 8290080 1CD223 

TRACK-ID = 00801 C-PEC = 82900801CD2U 

TRACK-ID = 00801 C-REC = 32900801CD25 

T9ACK-IP = 00801 C-PEC = 82900801CD26 



Figure 18. Sample Program for a Randomly Created Direct File (Part 2 of 2) 
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File 
Organization 


Dili Management 
Techniques 


Acceit 
Method 


KEY 

CIlUMf 


OPEN 
Statement 


Accta 
Verbi 


CLOSE 

Statement 




BSAM 


SEQUENTIAL 


ACTUAL 


INPUT 


READ (INTOl 
AT END 


[UNIT! 
[WITH LOCK] 


OUTPUT 


WRITE (FROM) 
INVALID KEY 


a 


BDAM 


RANDOM 


ACTUAL 


INPUT 


SEEK 

READ [INTO] 
INVALID KEY 


[WITH LOCK! 


OUTPUT 


SEEK 

WRITE (FROM) 
INVALID KEY 


l-O 


SEEK 

READ (INTOl 

INVALID KEY 
WRITE [FROM] 

INVALID KEY 


w 


BDAM 


RANDOM 


ACTUAL 


l-O 


SEEK 

READ [INTOl 

INVALID KEY 
WRITE! FROM! 

INVALID KEY 
REWRITE! FROM I 

INVALID KEY 


(WITH LOCK] 



t-3 



n 
o 
o 

fD 
CO 
CO 
H- 

3 
03 

O 

3 

3 

CD 
CO 
CO 

U) 

ft 
o 
n 

OJ 
03 
fD 

D 

< 
o 

0) 
CO 



Table 14. JCL Applicable to Directly Organized Files 



T T T T T T T 

DSNAKE | Device I UNIT VOLUME | LABEL | SPACE, SUBALLOC, SPLIT | DISP 



DD Statement Parameters Applicable to BSAM Input Files 



| Mass | not required | [SL or 
| Storage jif cataloged! SUL] 
j required | | 

I I I 



(old) 

\SHRJ 



, PASS J 
, KEEP f 
, CATLG > 
|, DELETE \ 
,UNCATLGl 



DCB 
na 






DD Statement Parameters Applicable to BSAM Output Files 



T T T T T T T' 

DSNAME | Device I UNIT VOLUME | LABEL | SPACE | SUBALLOC j SPLIT j 



DISP 



DCB 



as 



Mass 

Storage 

required 



[SL or 
SUL] 



as 

RLSE 



as 



na 



(, KEEP ) 
), CATLG f 



NEW i, KEEP 
CATLG 

i, PASS ( 
, DELETE) 

Note: MOD not 
meaningful 



[DSORG=DA] 
OPTCD=[W, T] 



DD Statement Parameters Applicable to BDAM Input and 1-0 Files 



T T T T T T 1" 

DSNAME | Device | UNIT VOLUME | LABEL | SPACE, SUBALLOC, SPLIT | 



DISP 



DCB 



as | Mass | not required | [SL or 
j Storage jif cataloged! SUL] 
j required j | 



na 



/OLD) I, PASS 
I SHR/ J, KEEP 
, CATLG 
, UNCATL 
, DELETE 



\ I «_rt.X.LAJ / 

J,UNCATLGl 
(, DELETE J 



| as specified 
j at file 
j creation 

I 



DD Statement Parameters Applicable to BDAM Output Files 



T T T T T T T" 

DSNAKE 1 Device I UNIT VOLUME | LABEL ! SPACE | SUBALLOC | SPLIT | 



DISP 



DCB 



4- 



as 



Mass 

Storage 

required 



[SL or | as 
SUB] | RLSE 



as 



NEW /, KEEP ) 
\ , CATLG f 

) , pass r 
( , delete) 

Note: MOD not 
meaningful 



[DSORG=DA] 

OPTCD=[W,E] 

LIMCT=n 



as = Applicable subparameters 
na = Not applicable 
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RELATIVE FILE PROCESSING 



Relative file processing is 
characterized by the use of the relative 
record addressing scheme. When this 
addressing scheme is used, the position of 
the logical records in a file is determined 
relative to the first record of the file 
starting with the initial value of zero. A 
NOMINAL KEY is used to identify randomly 
accessed records. Files with relative data 
organization must be assigned to mass 
storage devices. 



r 1 

| Format | 

y .| 

I I 

| NOMINAL KEY IS data-name | 

I I 

L J 



1. The records (Rl, R2, ..., Rn) are 
formatted without a key area. 

2. The COUNT area contains a record ID: 

a. 2 bytes containing the cylinder 
number. 

b. 2 bytes containing the read/write 
head. 

c. 1 byte containing a record number 
from 1 through 255. 



Records on mass storage devices will 
always appear sequentially ranging from 
to n, where n equals the highest key 
contained in the file. 

The following example illustrates the 
relationship between the NOMINAL KEY and 
the positioning of records on a mass 
storaye device. 



Data-name must be defined as an" 
8-integer binary item whose value must not 
exceed 16,777,215. NOMINAL KEY must be 
defined in the Working-Storage Section. 

The following example illustrates use of 
the NOMINAL KEY clause: 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS THE-NOMINAL-KEY. 



DATA DIVISION. 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS THE-NOMINAL-KE*. 



DATA DIVISION. 

FILE SECTION. 

FD RELATIVE- FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1 PIC X(80). 



WORKING-STORAGE SECTION. 



77 THE-NOMINAL-KEY PIC S9(8) COMP SYNC. 



WORKING-STORAGE SECTION. 

77 THE-NOMINAL-KEY PIC S9(8> COMP SYNC. 

L J 



The relative file processing technique 
supports only unblocked fixed-length 
records. 

Figure 19 illustrates those parts of a 
relatively organized file that are of 
importance to a COBOL programmer. The 
track format is similar to the format 
described for directly organized files (see 
section "Direct File Processing"). The 
following is a list of significant 
differences: 



Consider REC-1 being written 50 times. 
With each execution of the WRITE statement, 
the content of THE-NOMINAL-KEY is 
incremented by 1, from through 49. Since 
a 2311 mass storage device has room for 
only twenty- five 80-character records on 
each track (see "Determination of File 
Space" in "Direct File Processing") REC-1 
will be written as follows: 

• Relative records through 24 tfill be 
on the first track. 

• Relative records 25 through 49 will be 
on the second track. 
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INDEX 
POINT GAP 



RO 



Rl 



R2 



I I r i r t r i r 

V | | TRACK | J CAPACITY | | III II 

G | ADDRESS J G | RECORD | G | COUNT | DATA | G | COUNT | DATA | G 

L J L J L J. J L X J 

L J 

Figure 19. Relatively Organized Data as it Appears on a Mass Storage Device 



Count Data 



Count Data 



Count Data 



Count Data 



r t t r t 1 r r i r t i 

G 101,00, 1|REC-1| G |01,00, 2|REC-1| G | 01, 00, 3 | REC-1 | G G | 01, 00, 25 | REC-1 | 

1st TRACK | | (0) | | | (1) | | | (2) | | | (24) | 

L J. J L x J L x J ... L x J 



r t 1 r t 1 r t t r t t 

G |01,01,1|REC-1| G | 01, 01, 2 | REC-1 1 G | 01, 01, 3 | REC-1 1 G G| 01, 01, 25 | REC-1 | 

2nd TRACK | | (25) | | | (26) | | | (27) | | | (49) | 

L x J L x J L x J . . . L x J 



Figure 20. Sample Format of Two Tracks of a Relative File 



If the two tracks assigned to RELATIVE FILE 
are "cylinder 01 track 00" and "cylinder 01 
track 01, " they would appear as shown in 
Figure 19. 

It is important to note that information 
about the length of each record, the 
capacity of each track and the relative 
record number, as indicated by the NOMINAL 
KEY is used by the system to determine the 
exact location of each record. As 
indicated in Figure 20, the system converts 
each relative record number into a unique 
cylinder number, head number, and record 
number, which are written in the count area 
of each physical record. 



Note : Since count areas do not appear in 
1-0 buffers and there are no key areas, 
buffer size need be only large enough to 
accommodate data in REC-1. 



Sequential Creatio n 



Relative files must be created 
sequentially using the file processing 
technique BSAM (Basic Sequential Access 
Method) . 



• The associated COBOL statements are 
summarized in Table 15. 

• The associated JCL statements are 
summarized in Table 16. 

Figure 21 illustrates the creation of a 
relative data set. 



Records in relative files, are arranged 
sequentially in the order in which they 
were written. The first record written is 
relative record 0, the second record is 
relative record 1, the nth record written 
is relative record n-1. A file containing 
1000 records will thus contain relative 
records through 999. The clause that 
allows the user to specify the relative 
record needed is the NOMINAL KEY clause. 

When a relative file is being created, 
the NOMINAL KEY clause may be specified. 

• If the NOMINAL KEY is specified and the 
value in the NOMINAL KEY (when a WRITE 
statement is executed) is greater than 
the next sequential relative number, 
the necessary number of dummy records 
is written by the compiler so that the 
actual record is written in the 
specified relative position. If tne 
NOMINAL KEY for a WRITE statement is 
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less than the next sequential relative 
record number, the key is ignored and 
the record is written in the next 
available position. 

• If the NOMINAL KEY is not specified, 
the system begins writing at relative 
record and increments the relative 
record number by 1 for each additional 
WRITE statement. When the key is not 
specified, the user is responsible for 
insertion of dummy records. The only 
time the compiler will add dummy 
records is during the execution of a 
CLOSE or CLOSE UNIT statement. 

Note : Dummy records are identified by 
the presence of the figurative constant 
HIGH-VALUE in the first position of the 
record. 



The relative block number of the last 
record written is placed in the NOMINAL KEY 
after a WRITE, CLOSE, or CLOSE UNIT 
statement, if the key is specified. 

Once a file is created, more space 
cannot be allocated and the extent of the 
file cannot be increased. The only way to 
add records to an already existing file is 
to replace dummy records. Therefore, to 
allow for future additions, the user should 
create the file with as many excess dummy 
records as desired. 



available. The RLSE subparameter of 
the DD statement applies only to the 
allocated tracks at the end of a data 
set. 

Note : In order to determine the amount of 
space a data set requires, see Tables 9-11. 



The file processing technique used to 
read a relative file sequentially is BSAM 
(Basic Sequential Access Method). 

• The associated COBOL statements are 
summarized in Table 15. 

• The associated JCL parameters are 
summarized in Table 16. 



When a relative file is being read 
sequentially, the records are made 
available in the sequence in which the 
records were written. Dummy records are 
also made available. The NOMINAL KEY, if 
specified, will be ignored. 



Random Access 



The allocation of space to a relative 
file (both single- volume and multi volume) 
is similar to the allocation of space 
described for a sequentially created direct 
file. Highlights and essential differences 
are discussed below: 



The file processing technique used to 
read or update a relative file randomly is 
BDAM (Basic Direct Access Method). 

• The associated COBOL statements are 
summarized in Table 15. 



• The relative file processing technique 
does not include a TRACK-LIMIT clause. 
Space allocation and formatting will, 
therefore, be determined by an 
interaction between the SPACE parameter 
of the DD card and the number of 
records written. 

• The total number of tracks formatted 
will be determined when the file is 
closed. Dummy records will be added to 
complete the current track, if 
necessary. 

• Tracks that are allocated but 
unformatted, and have been requested in 
track or block units, can be released 
by specifying the RLSE subparameter on 
the DD statement. 

• When a unit of a multivolume file is 
closed, all tracks that have been 
allocated on the current unit are 
formatted ( initialized with dummy 
records) before the next unit is made 



The associated JCL statements are 
summarized in Table 16. 



Since a relative file cannot be created 
randomly, the following restrictions exist: 

1. The file cannot be opened as an output 
file. 

2. The WRITE verb is not permitted. 



A relative file with BDAM can be opened 
as input or 1-0. Records are made 
available according to the contents of 
NOMINAL KEY. If the user wishes to update 
a file, it must be opened as 1-0. Records 
can then be read into a single buffer, 
updated in that buffer, and rewritten from 
that buffer. If the user wishes to add 
records to a file, the file must have been 
created with excess dummy records. If 
dummy records are present, the file can be 
opened as 1-0 and dummy records can be 
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replaced by the additions. If dummy 
records are not present, additions cannot 
be made. 

Note : Records cannot be deleted, but can 
be replaced by dummy records. 

Figure 21 illustrates several basic 
characteristics of the relative file 
processing technique. It creates a 
relative file (R-FILE) using a card file 
(C-FILE) as input. C-FILE consists of 11 
cards in the following sequence: 



Card 






Number 




Card Contents 


1 


010 


NAME 01 


2 


020 


NAME02 


3 


030 


NAME03 


4 


040 


NAME04 


5 


050 


NAME05 


6 


060 


NAME06 


7 


000 


THIS CARD IS OUT OF SEQUENCE 


8 


070 


NAME 07 


9 


080 


NAME 08 


10 


090 


NAME09 


11 


100 


NAME10 



The program, during creation, exhibits 
the contents of NOMINAL KEY after the 
execution of each WRITE statement. After 
creation, the relative file is closed, 
reopened as an input file, and written out 
on the printer. The following discussion 
highlights some basic features. Circled 
numbers in the program example refer to 
corresponding numbers in the text. 

1. The nominal keys, \lj , that have been 
exhibited contain the relative record 
numbers of real records on the file. 
Relative records 10, 20, 30, 40, 50, 
60, 61, 70, 80, 90, and 100 are real; 
all others are dummy records formatted 
by a COBOL subroutine. Note the 



nominal key N-KEY = 61. The initial 
value taken from C-FILE, card 7, was 
000. This value, however, was not in 
logical sequence since relative 
records 000 through 060 had already 
been written. Therefore, a COBOL 
subroutine ignored the value 000 and 
adjusted it to the next appropriate 
relative record number (i.e., 61). 

2. The contents of N-KEY for the first 
WRITE, (2J , was 10. This means that 
a COBOL subroutine formatted relative 
records through 9, placing the 
constand HIGH-VALUE in the first 
position of each record. 

Note : The constant HIGH- VALUE is 
exhibited as a blank since FF is not a 
printable character. 

3. The contents of N-KEY for the second 
WRITE, ^3J , was 20. Therefore, the 
COBOL subroutine formatted relative 
records 11 through 19. 

4. The contents of N-KEY for the seventh 
WRITE, (4) , was initially 000. As 
explained in step 1 , N-KEY was 
adjusted to 61 and the record was 
written in the next available 
position. 

5. Since this file was created on a 2311 
mass-storage device, the track 
capacity for R-FILE is 2 5 record per 
track. Relative record 100 is, 
therefore, the first record written on 
track 4 (remember: the first 5 tracks 
of a file are actually relative tracks 
through 4). Since the file is 
closed after writing relative record 
100, the COBOL subroutine formats the 
rest of track 4. In this case, it 
means the addition of 24 dummy 
records, Co\ 
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00001 
00002 
00003 
00004 
00005 
00006 
00007 
00008 
00009 
00010 
00011 
00012 
00013 
00014 
00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 
00025 
00026 
00027 
00028 
00029 
00030 
00031 
00032 
00033 
00034 
00035 
00036 
00037 
00038 
00039 
00040 
00041 
00042 
00043 
00044 
00045 
00046 
00047 
00048 
00049 
00050 
00051 



00101 

00102 

00103 

00104 

00105 

00106 

00107 

00108 

00109 

00110 

00111 

00112 

001125 

001126 

001127 

00113 

00114 

00115 

00116 

00117 

00118 

001184 

001185 

001186 

00201 

00202 

00203 

00204 

002041 

002042 

002043 

002044 

002045 

002046 

00205 

00206 

002 07 

002 08 

00209 

00210 

00211 

00212 

00213 

00214 

00215 

00216 

00217 

00218 

00219 

00220 

00230 



IDENTIFICATION DIVISION. 

PROGRAM- ID. CREATER. 

REMARKS. ILLUSTRATE CREATION OF A RELATIVE FILE. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM- 360. 

OBJECT-COMPUTER. IBM- 3 60. 

INPUT- OUTPUT SECTION. 

FILE-CONTROL. 

SELECT R-FILE ASSIGN DA-2311-R-MASTER 
ACCESS IS SEQUENTIAL 
NOMINAL KEY IS N-KEY. 

SELECT C-FILE ASSIGN UR-S-CARDS. 

SELECT R-FILE2 ASSIGN DA-2311-R-MASTER. 

SELECT PRTFILE ASSIGN UR-S-PRTOUT. 
DATA DIVISION. 
FILE SECTION. 
FD R-FILE 

LABEL RECORDS ARE STANDARD 

RECORDING MODE IS F 

DATA RECORD IS DISK. 

DISK PIC X(80). 

R-FILE2 LABEL RECORDS ARE STANDARD. 

DISK2 PIC X(80). 

C-FILE 

LABEL RECORDS ARE OMITTED 

DATA RECORD IS CARD. 

CARD. 

02 C-KEY PIC 9(3). 

02 FILLER PIC X(77). 

PRTFILE LABEL RECORDS ARE OMITTED. 

PRT. 

02 FILLER PIC X. 

02 FIELD1 PIC X(132). 
WORKING-STORAGE SECTION. 
77 N-KEY PIC S9(8) COMP SYNC. 
PROCEDURE DIVISION. 

OPEN INPUT C-FILE 

OUTPUT R-FILE. 
Rl. READ C-FILE AT END GO TO EOJ1. 

MOVE C-KEY TO N-KEY. 

WRITE DISK FROM CARD. 

EXHIBIT NAMED N-KEY. GO TO Rl. 
EOJ1. 

CLOSE C-FILE R-FILE. 

OPEN INPUT R-FILE2 OUTPUT PRTFILE. 
R2. READ R-FILE2 AT END GO TO EOJ2. 

MOVE DISK2 TO FIELD1. 

WRITE PRT AFTER 1 LINES GO TO R2. 
EOJ2. 

CLOSE R-FILE 2 PRTFILE. STOP RUN. 



01 
FD 
01 

FD 



01 



FD 
01 



Figure 21. Sample Program for Relative File Processing (Part 1 of 4) 
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1EF2B5I PPOCPAST PASSED 

IEF285I VCL SEP NCS« LSASIA. 

IEF285I SYS6S1E4.TC3C422.RVCCC.RFILE.LT1 CELETED 

IEF285I VCL SEP NCS- KVTRES. 

IEF285I SYS69184.TC3C423.RV000.RFILE.AJCB PASSED 

IEF285I VCL SEP NOS« 222222. 

IEF28SI SYSl.CCeLie KEPT 

IEF265I VCL SEP KOS- ISASIA. 

IEF285I SYSeSlE4.TC3C423.SVCCC.PFILE.RC0CC032 SYSCIT 

IEF285I VCL SEP NOS» 231400. 

IEF28«I SYS6MC4.7C3C423.RVC0C.RFIIE.FKCH CELETEC 

1EF285I VCL SEP NOS« 222222. 

STEP STEP2 TERHMTEC. TIPE CO.CC 1-R.HCRTF/hR » CC. CO. 18.08 HR.PU.SEC.HORTH/SEC»CATE 6S.184 

//STEP3 EXEC PGP«*.STEP2.SYSLPCC 

//SYSCUT DC SYSCUT-A 

//SYSLDUPP CC SYSCLT** 

//MASTER DC LMT«23ll ,VCLUP E>SEP«C«C28 t SFACE-<TRK , J5 ,5 ) » .CCKT 1G 1 , X 

// CSKAME«RFILE,CISP*(KEti.KEEP) 

//PRTCUT CC SYSCLT** 

//CARDS PO • 

// 

IEF236I ALLCC. FCR RF1LE STEP3 

IEF237I JCBLIB CN 1S3 

1EF237I FG*«*.CD CN ISC 

1EF237I <YSCLT CN 23C 

1EF237I SYSLOLPF CK 23« 

IEF2371 MASTER CN 1S2 

1EF237I PRTCLT CK 23C 

1EF257I CAROS CK 23« 

K-KEY « CCCCCC1C 
N-KEY * CC0CCC2C 
K-KEY » C00C0030 
N-KEY « CCCCCC4C 
N-KEY * CCCCCCfC 
N-KEY « C000C06C 
N-KEY » CCCCCC61 
N-KEY * C0C00C7C 
K-KEY » CCCC0C8C 
N-KEY * CCCCCC«C 
K-KEY « C00001CC 



10 NAHEC1 

10 KAPEC1 

10 KAPE01 

10 KAPE01 

10 KAfEOl 

10 KA*E01 

10 MKE01 

10 KAPE01 

10 MPE01 

10 KAMEC1 

010 KAP»E01 

20 KA»E02 

20 KAPE02 

20 KAPEC2 

20 KAfE02 

20 KA*E02 

20 KAPE02 

20 KAPEC2 

20 NAPEC2 

20 K»fEC2 



© 



© 



© 



Figure 21. Sample Program for Relative File Processing (Part 2 of 1) 
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u*:u 


iva'tu* 


30 


t.A*EC3 


30 


^*|»EC^ 


30 


MPEC3 


30 


^*I»6C3 


30 


MKEC3 


30 


^*^'€C3 


30 


^AMEC3 


30 


MKEC3 


30 


&AKEC3 


030 


MKEC3 


40 


KA*E04 


40 


KAfE04 


40 


KA*E04 


4C 


M*E04 


40 


KA*E04 


40 


KA*E04 


40 


KA¥ E04 


40 


KAf E04 


4C 


^A^<E04 


040 


KA*E04 


50 


MfEC5 


50 


^A^'E05 


50 


KAfE05 


50 


^A^»E05 


50 


^A^»E05 


50 


KA*E05 


50 


^A^'E<^5 


50 


^A^'EC5 


50 


^A^'E05 


050 


HAPEC5 


60 


KA^EOfc 


60 


KA»E06 


60 


►AfEOC 


60 


^AKEC6 


60 


KAfEC6 


60 


^A^'E06 


60 


KACE06 


60 


*a*E06 


6C 


MKE06 


060 


*AfEC6 


000 


TUS CAPC 


70 


KA*E07 


70 


^A^'E07 


70 


KA*E07 


70 


MKE07 


70 


MKE07 


70 


KAf E07 


70 


KAKE07 


70 


hA*E07 


070 


MfE07 


80 


^A»'EC8 


80 


^AKE08 


80 


KAfEOS 


80 


KAKE08 


80 


KAPE08 


80 


KANEC8 


80 


MKEC8 


80 


KA^EOO 


80 


fAPECB 


080 


M*EC8 


90 


t>A»E09 


SO 


KA»EC9 


<»0 


KAP»EC9 


«;c 


na*ec<; 


90 


^A^E09 



IS CLT CF SEQUENCE 



© 



Figure 21. Sample Program for Relative File Processing (Part 3 of 1) 
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«*0 




A*eC» 


90 




APEO? 


90 




A»E0<3 


90 




AfECS 


090 




ACE09 


00 


KA 


*E10 


00 


KA 


fElO 


00 


KA 


NE10 


00 


KA 


KE10 


00 


KA 


HEIO 


00 


KA 


fElO 


00 


KA 


fElO 


00 


KA 


PE10 


00 


ka 


fElO 


100 


KA 


PE10 


00 


KA 


*E10\ 


00 


KA 


»»E10 


00 


M 


M£1Q 


00 


KA 


mo 


00 


KA 


KE10 


00 


KA 


CE10 


00 


KA 


»»E10 
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Figure 21. Sample Program for Relative File Processing (Part 4 of 4) 
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Data Management 


Access 


KEY 


OPEN 


Access 


CLOSE 


Techniques 


Method 


Gauses 


Statement 


Verbs 


Statement 


BSAM 


SEQUENTIAL 


INOMINALI 


INPUT 


READ [INTO] 


IUNIT] 










AT END 


IWITII LOC'KI 






NOMINAL 


OUTPUT 


WRITE [FROM] 
INVALID KEY 




BDAM 


RANDOM 


NOMINAL 


INPUT 


READ [INTO] 
INVALID KEY 


[WITH LOCK] 








INPUT 


READ IINTO] 
INVALID KEY 










OUTPUT 


REWRITE [FROM] 
INVALID KEY 
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Table 16. JCL Applicable to Relatively Organized Files 

r 



DD Statement Parameters Applicable to BSAM Input Files 



T T T T T T" 

DSNAME | Device I UNIT I VOLUME | LABEL | SPACE, SUBALLOC, SPLIT | 
J- 4- J- 4- 4- 4~ 



DISP 



DCB 



as JMass j not required j [SL or 
I Storage j if cataloged j SUL] 
j required j | 



(OLD) (, PASS 
tSHR/ \ KEEP 

, CATLG 
', DELETE 
., UNCATLG, 



DD Statement Parameters Applicable to BSAM Output Files 



T T T T T T T T" 

DS NAME | Device I UNIT I VOLUME | LABEL | SPACE | SUBALLOC | SPLIT | 
J. 4- X 4- X 4- 4- 4.- 



DISP 



DCB 



as 



Mass 

Storage 

required 



as 



[SL or | as 
SUL] I RLSE 



as 



na 



NEW { , KEEP 
I , CATLG 
j , PASS 
', DELETEl 

Note : MOD not 
meaningful 



OPTCD={W l T} 
[DSORG=DA] 



DD Statement PARAMETERS Applicable to BDAM Input and 1-0 Files 



T T T T T T' 

DSNAME | Device I UNIT I VOLUME | LABEL | SPACE, SUBALLOC, SPLIT | 
4- 4- X 4- 4- A. 



DISP 



DCB 



as | Mass | not required | [SL or 
j Storage jif cataloged! SUL] 
j required j | 



na 



/OLD\ (, PASS 

IshrI \,keep 

, CATLG 
.UNCATLG! 
, DELETE 



J. 4. ±. 

as = Applicable subparameters 
na = Not applicable 



| as has been 
j specified 
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INDEXED FILE PROCESSING 



The indexed file processing technique 
arranges records on the tracks of a 
mass-storage device in a sequence 
determined by keys. The key is a control 
field that is a physical part of the record 
(defined in the FD) and is specified by the 
RECORD KEY clause in the Environment 
Division. The RECORD KEY clause identifies 
for the compiler the location and length of 
that item within the data record that will 
contain the key. It must always be 
specified. 



r 1 

| Format | 

j. -I 

I I 

| RECORD KEY IS data-name | 

I I 

L J 



D ata-name may be any fixed-length item 
from 1 through 255 bytes in length. 

When two or more record descriptions are 
associated with a file, a similar field 
must appear in each description, and must 
be in the same relative position from the 
beginning of the record, although the same 
data-name need not be used for both files. 

Data-name must be defined to exclude the 
first byte of the record in the following 
cases : 

1. Files with unblocked records. 

2. Files from which records are to be 
deleted. 

3. Files whose keys might start with a 
delete-code character ( HIGH- VALUE) . 



With these exceptions, the item 
specified by data-name may appear anywhere 
within the record. 



The position of each logical record in a 
file is determined by indexes created with 
the file and maintained by the system. The 
indexes are based on the RECORD KE¥S and 
provide the following capabilities: 

• Write and later read or update logical 
records in a sequential, ascending 
order (using QISAM) based on the 
collating sequence of the keys. This 
is done in a manner similar to that for 
sequential organization. 

• Read or update individual logical 
records in a random manner (using 
BISAM) . This method is somewhat slower 
per record than reading according to a 
collating sequence, since a search for 
pointers in indexes is required for the 
retrieval of each record. 

• Insert new logical records at any point 
within the file (using BISAM). Using 
the indexes, the system locates the 
proper position for the new record and 
makes all necessary adjustments so that 
the sequence of the records, according 
to the keys, is maintained. 



Indexes 



There are two basic types of indexes: 
track indexes and cylinder indexes. There 
is one track index for each cylinder in the 
prime area (see "Indexed File Areas" for a 
description of prime area) . The track 
index is written on the first track of the 
cylinder that it indexes. Each entry in 
the track index contains the identification 
of a specific track in the cylinder and the 
highest key on that track (Figure 22). 

Figure 22 is the representation of a 
track index with the following areas: 

Home Address -- This field defines the 
physical location of the track in 
which the index appears. It 
indicates the cylinder in which the 
track is located and the read/write 
head that services the track. 



RO 



Normal 



Overflow 



Normal 



Overflow 



— T 



r t r 1 r t 1 r t 1 r t 1 r t 1 

j 0100 j |COCR| |00010|000lj | 00010 | 0001 1 |00025|0002| j 00025 j 0002 | 

L J L J L JL J L X J L X J L X J 



Home 
Address 



Key 



Data 



Key 



Data 



Key 



Data 



Key 



Data 



L J 



Figure 22. Track Index 
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CQCR (Cylinder Overflow Control Record) 
— When a cylinder overflow area is 
specified (see "Indexed File Areas" 
for a description of overflow 
areas), RO of each track index is 
used to keep track of overflow 
records and space available in the 
cylinder overflow area. 



N ormal Entry — There is one normal and 
one overflow entry for each usable 
track in the cylinder. The Normal 
Entry contains two areas: 



— the key of the highest 
record on the track specified in 
the Data area 



• Data — the home address of one of 
the prime tracks in the cylinder 



Figure 22 shows that the highest key 
on track 1 is 10 and the highest key 
on track 2 is 25. 



O verflow Entry — The overflow entry is 
originally the same as the normal 
entry. It is changed when an 
attempt is made to add a record to a 
prime track on which space is no 
longer available. In this case, the 
overflow entry keeps track of the 
logical sequence of records although 
physically the record may be added 
to an overflow area. 



r t t r t t r t 1 

| 00500 | 00001 j00945| 0001] 1 01550 | 0002 | . 



^„.,t -: „^j^^ -. ,q .3 „ ^ ^ ,-. s 



Key Data Key Data Key Data 

I 

cylinder address 
Figure 23. Cylinder Index 



The cylinder index is formatted in the 
same fashion as the track index. Figure 23 
shows that the highest key on cylinder is 
500, the highest key on cylinder 01 is 945, 
the highest key in cylinder 02 is 1550, 
etc. 



Note; If an indexed file is being read 
randomly, the system locates the given 
record by its key after a search of the 
cylinder index and the track index within 
the indicated cylinder. If the file is 
being read sequentially, starting, with the 
first record, no index search is performed. 

Records, in indexed files, may be either 
blocked or unblocked; but must be F-mode 
records. Figures 24 and 25 illustrate 
blocked and unblocked records as they 
appear on prime tracks of mass storage 
devices. 

BLOCKED RECORDS 



Count: contains control information 



There is one cylinder index for each 
file in which prime area data occupies more 
than one cylinder. The cylinder index 
contains one entry for each cylinder in the 
prime area; each entry pointing to the 
track index for a particular cylinder 
(Figure 23). 



Key: contains the key of highest record in 
the block 



Data(l| 2j . . . | 6)_: each contains the 

information defined in the FD; including 
its own record key. 



r T T T T 1 f T T T T 1 

I COUNT j KEY | DATA1 | DATA2 | DATA3 | j COUNT | KEY | DATA4 | DATA5 | DATA6 | 
L J. J. X J. J L i. J. J. J. J 



1st Block 



2nd Block 



Figure 24. Blocked Records on an Indexed File 
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r t t 1 

I COUNT j KEY j D ATM | 
L J. X_ J 

1st Block 



r t t 1 l 

j COUNT | KEY |DATA2| \ 

L X- --X. J | 

2nd Block 



Figure 25. Unblocked Records on an Indexed 
File 



prime area on more than one cylinder. 
Space for this area will be allocated 
separately from the prime area if 
specifically requested. The index area 
must be contained within one volume, but 
that volume need not be the same device 
type as the prime area volume. If not 
specifically requested, the index area will 
automatically be constructed in the 
independent overflow area, or, if there is 
no independent overflow area, it is 
constructed in the prime area. 



UNBLOCKED RECORDS 
Count: contains control information 



Key: contains the key of the record that 
is in the block. 



D ata (1), (2) , etc . : each contains the 

information defined in the FD; including 
its own record key. 



Indexed File Areas 



Overflow Area : The overflow area is the 
area in which space is allocated for 
records forced from their original (prime) 
tracks by the insertion of new records. 
The fact that some records are stored in 
these areas, physically out of sequence, 
does not change the ability of QISAM to 
read the file in a logical sequence. An 
overflow area need not be specified if 
records are either not going to be added to 
the file, or sufficient space was 
originally reserved by writing dummy 
records in the prime area. 



The programmer specifies the structure 
of an indexed file and space to be 
allocated for it in the DD statement for 
the file when the file is created. In some 
instances, more than one DD statement is 
required. (These DD statements are 
described in "Using the DD Statements -- 
Single Volume Files.") The space being 
allocated must be divided into one, two, or 
three areas, depending on the needs of the 
programmer. These areas are: prime area, 
index area, and overflow area. The 
overflow area is optional. 



Prim e Are a: The prime area is the area in 
which data records are written when the 
file is created or reorganized. These 
records are in a sequence determined by the 
record keys. The track indexes also use a 
portion of the reserved prime area. To 
reserve prime area space so that new 
logical records may be inserted without 
forcing records into an overflow area 
(described below), dummy records (records 
containing the figurative constant 
HIGH-VALUE in the first character position) 
may be written when the file is being 
created. The prime area may span multiple 
volumes and may consist of several 
noncontiguous areas. 



Inde x Area : The index area contains the 
cylinder indexes and, if requested, master 
indexes (described later) for the file. 
This area exists for any file that has a 



There are three ways in which space for 
an overflow area may be allocated: 



1. Cylinder Overflow (Figure 26). Tracks 
on each cylinder can be reserved to 
hold the overflow of that cylinder 
(cylinder overflow option). 



2. Independent Overflow (Figure 27). 
Space may be requested for an 
independent overflow area, using the 
dsname (OVFLOW) DD statement, either 
on the same volume or on a separate 
volume of the same device type as that 
of the prime area. 



3. If the prime area is not filled when 
the file is created, the space 
remaining on the last cylinder on 
which data has been written will be 
designated as an independent overflow 
area (even though it is not requested 
directly). If a separate independent 
overflow area is requested, the 
remainder of the prime area is 
available for resuming a load 
operation. 

Additional information about indexed 
file structure is contained in the 
publication IBM OS Data Management 
Services. 
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I I I 

CYLO | CYL1 | CYL2 | CYL3 | CYL4 | CYL5 | CYL6 

I- + + + + + + H 

| Track Indexes 
I- + + + + + + ^ 

I I I 

i I I 

Prime Area 

I I I 
I I I 
I 1 I 

III 
y 4- 4- X 4 + + 1 

I I I I 

Cylinder Overflow Area 

I I I 

L J J. X J. X X J 

L J 

Figure 26. Cylinder Overflow Area 



Creating Indexed Files 



Indexed files must be created 
sequentially using QISAM (Queued Indexed 
Sequential Access Method) . Records must be 
arranged and written in ascending order 
according to the contents of RECORD KEY. 
If a WRITE statement is executed and the 
current contents of RECORD KEY is less than 
or equal to the previous contents of RECORD 
KEY, an INVALID KEY condition will result. 



The structure of an indexed file, and 
the space to be allocated to it, is 
specified in a DD statement (s ) . The space, 
which can be allocated in several different 
ways, must be sufficient for all areas of 
the file. 



An advantage of having a cylinder overflow 
area is that additional seek operations are 
not required to locate overflow records. A 
disadvantage is that there will be unused 
space if additions are unevenly distributed 
throughout the file. 



r 1 



DD STATEMENT REQUIREMENTS FOR INDEXED 
FIL ES; The special parameter requirements 
for DD statements that define new indexed 
files are discussed below. The discussion 
is oriented to indexed files on one volume. 
Many of the parameters used for creating 
multi volume files are not discussed here. 
For more detailed information about 
parameters for both single-volume and 
multivolume files, see either of the 
publications IBM O S Jo b C ontr ol L anguage 
E§f §E§Q2§ or I?M OS_Job_Cqntrol Language 
Programmer' s Guide. 



I I I I I 
| CYLO j CYL1 1 CYL2 j CYL3 | 
y 4 4 4 .| 

| Track Indexes | 

I- + + + ^ 

I I I I I 

| Prime Area | \ 



CYLX JCYLY 
i— — + -I 



Independent | 
Overflow 
Area 



l x x x J 



l x J 



l j 

Figure 27. Independent Overflow Area 



An advantage of having an independent 
overflow area is that less space need be 
reserved for overflows. A disadvantage is 
that accessing overflow records requires 
additional seek operations. 



A suggested approach is to have cylinder 
overflow areas large enough to contain the 
average number of overflows caused by 
additions and an independent overflow area 
to be used as the cylinder overflow areas 
are filled. 



ddname (name field) 

The name field of the first or only DD 
statement defining the indexed 
sequential file can contain the 
symbolic identification ddname or 
procstep. ddname. Succeeding DD 
statements for the file must not be 
named. 

DSNAME (DSN) 

This parameter must be specified and 
is coded as follows: 




\dsname/ 






SSname 






[ (element) ] 



The first subparameter, dsname, or 
Uname must be the same in all the DD 
statements defining one data set. The 
element subparameter, INDEX, PRIME, or 
OVFLOW, indicates the type of area 
defined by the DD statement. If more 
than one DD statement is used to 
define a file, the order in which the 
statements should be placed in the 
input stream is as follows: 

DD DSNAME=dsname ( INDEX) 
DD DSNAME=dsname ( PRIME) 
DD DSNAME=dsname< OVFLOW) 
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Deviation from this sequence results 
in abnormal termination of the job. 
If the element subparameter is omitted 
PRIME is assumed. Note that an 
indexed file cannot be specified by 
statements containing only index and 
overflow elements. 



SPACE 



This parameter specifies the space to 
be allocated for each of the separate 
areas on the device and must be 
included. Only cylinder (CYL) or 
absolute track (ABSTR) requests are 
permitted, and with ABSTR the 
designated tracks must encompass an 
integral number of cylinders. All the 
DD statements defining one indexed 
file must specify the same 
subparameter, either CYL or ABSTR. 
When all the DD statements specify 
CYL, all must also specify or omit 
CONTIG, depending on whether the space 
allocated is to be contiguous or 
noncontiguous. The directory or index 
quantity subparameter of the SPACE 
parameter is used to request the 
number of cylinders to be allocated 
for an index area embedded within the 
prime area (see "Space Parameter" in 
"Job Control Procedures"). An 
embedded index resides in the middle 
of a track and saves searching time by 
first determining which half of the 
track contains the requested record. 



SPLIT 



DISP 



DCB 



This parameter should never be 
specified for an indexed file, either 
for sharing a cylinder with indexed 
files or for sharing it with an 
indexed file and another type of file. 



This parameter is written as it would 
be for any new file that cannot be 
cataloged. The CATLG subparameter 
must not be specified unless only one 
DD statement is used to allocate the 
file space (see "Cataloging Files" for 
additional information about 
cataloging indexed files). 



This parameter must be specified for 
each DD statement and is coded as 
follows : 

DCB=(DSORG=IS 

[,BUFNO=integer] 

t , OPTCD= {Y|I|R|W|L|M|U, NTM=integer } ] 

[ , BLKSIZE=integer] ) 

The DSORG=IS subparameter is required 
and indicates that the organization of 
the file is sequential. The DCB 
subparameters of all the DD statements 
defining one file must not conflict. 



For example, if the OPTCD=Y 
subparameter appears in the first DD 
statement, the subsequent DD 
statements should also contain 
OPTCD=Y. To avoid any errors, code 
all the DCB subparameters on the first 
DD statement. Code DCB=*.ddname on 
the remaining statements; ddname is 
the name of the DD statement that 
contains the DCB subparameters. The 
subparameters are discussed below. 

BUFNO=number of buffers 

This subparameter is used to specify 
the number of buffers to be assigned 
to the file if no RESERVE or SAME AREA 
clause is specified for the file in 
the source program. The maximum 
number is 255; however, the maximum 
number allowed for an installation iray 
differ and is established at system 
generation time. 

OPTCD=options 

This subparameter is used to tell the 
system that certain additional 
facilities are to be provided for this 
file. Any combination of the 
following options can be specified for 
the OPTCD subparameter. If more than 
one option is specified, the options 
are written as a character string 
(i.e., without intervening commas or 
blanks). Note that if certain of 
these options are used, an additional 
subparameter must also be specified as 
indicated. In addition to the 
information supplied, the following 
default services are provided: (1) 
the COBOL compiler will supply 
OPTCD=L; and (2) in the case of an IBM 
2321 mass storage device, the 
operating system will supply OPTCD=W. 

• OPTCD=L: This option requests 
that the control program delete 
marked records. Marked records 
will be deleted when space for 
new records is required. 

• OPTCD=Y: This option requests 
that a cylinder overflow area be 
created. It specifies that a 
certain number of tracks on each 
cylinder are to be reserved to 
contain any overflow records 
from other tracks on that 
cylinder. Another DCB 
subparameter, CYLOFL=xx, must 
also be written. The xx 
specifies the number of tracks 
on the cylinder to be reserved 
for the overflow area. The 
maximum number is 99. 

• OPTCD=I: This option requests 
that an independent overflow 
area be reserved. It is used in 
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conjunction with DSNAME=dsname 
(OVFLOW) parameter in the DD 
statement used to allocate the 
independent area. 

• OPTCD=M: This option requests 
that a master index be created 
(see "Master Index" for a 
discussion of master indexes). 
Another DCB subparameter, 
NTM=xx, must also be written. 
It specifies the maximum number 
of tracks to be contained in the 
cylinder index before a higher" 
level index is created. The 
maximum value that can be 
specified is 99. 

• OPTCD=R: This option requests 
reorganization criteria 
feedback, as described in 
"Reorganizing Files. " 

• OPTCD=W: This option requests 
the system to perform a write- 
validity check. 

• OPTCD=U: This option requests 
that track index entries be 
accumulated in core storage 
until there are enough entries 
to fill a track. When the track 
is full all the entries will be 
written out. If enough core 
storage cannot be obtained 
entries will be written two at a 
time. 



Using the DD St atements — Single-Volume 
Files : The following examples refer to 
files that can be contained on one volume. 
Additional information about DD statements, 
including details on multivclume file 
allocation, can be found in the publication 
IBM OS Job Control Language Reference . 



All three areas for an indexed file can 
be contained on a single volume if they are 
small enough. If such is the case and the 
programmer elects to allow the system to 
subdivide storage into the prime and index 
areas when the file is created, he need 
only code the following DD statement: 



//ddname DD DSNAME=dsname ( PRIME) , 
// SPACE=(CYL, (no. of 

// cylinders) ) , UNIT=unit, 

// DCB= (DSORG=IS, ) 



The DD statement given will produce a prime 
area with the index area occupying the last 
cylinder (s) of the space in the prime area. 
If any track (s) remain on the last cylinder 
after the index area, they are used as an 
independent overflow area; if no track(s) 
remain, an overflow area does not exist. 



If the programmer definitely wants an 
independent overflow area, he must provide 
a second DD statement as follows : 



//ddname DD DSNAMS=dsname ( PRIME ) , 



The following is an example of how 
the OPTCD subparameter can be used: 

DCB= ( DSORG= I S , OPTCD=M, NTM= 2 ) 



The foregoing example requests that a 
master index be created when the 
cylinder index exceeds 20 tracks. 



// 
// 
// 
// 
// 
// 
// 
// 
// 



SPACE=(CYL, (no. of 
cylinders) ) , UNIT=unit, 
VOLUME=3ER=222222, 
DCB= (DSORG=IS, 0PTCD=I, 
DD DSNAME=dsname ( OVFLOW ) , 
SPACE=(CYL« (no. of 
cylinders) ) , UNIT=unit, 
VOLUME=SER=222222, 
DCB=*. ddname 



. ) 



BLKSIZE=integer 

specifies the blocksize. This clause 
is used only if BLOCK CONTAINS 
RECORDS was specified at compile time. 



These DD statements will produce a prime 
area and a separate overflow area with the 
index area at the end of the overflow area. 
All three areas reside on the same volume. 



WULC . 



- y U.X. <= £. KJ 



may be used in a DD statement when 
processing indexed files opened as output. 
Additional information about indexed file 
structure is contained in the publication 
IBM OS D ata Manage m ent Services . 



Note : When more than on DD statement is 
used, only the first can be named. The 
others must not have a data definition name 
(ddname) but all must have the same data 
set name (dsname). 



User File Processing 115 



ddname | ddname used only for first DD 
j statement of each file 


DSNAME j jdsname( (INDEX) 
(DSN) | )£Sname[ (PRIME) 
j ( OVFLOW) 
j Note: If more than one DD 
j statement is used, elements 

jmust be in this order. 
j. _ 


— _ -j. _ 

Device |Mass storage required 
- 4— 


T 

UNIT | DEFER not permitted 

- - 4- - 


T 

SEP, AFF| Restricted, see "Job Control 

j Procedures" 

j. _ 


VOLUME | Volume sequence number subparam- 
j eter not applicable 
_4. _ 


T 

LABEL | SL 

i _ 


SPACE | CYL .... [..CONTIG] 
| ABSTR 
± _ 


T 

SUBALLOC|Not applicable 

-4. _ _ _ 


T 

SPLIT |Not applicable 
4. 


T 

DISP | 

| NEW 1 

_ _ 4 _ _ __ 


.KEEP 
.PASS 
, DELETE 




T 

DCB 2 | Required: DSORG=I£ 
j Optional: BUFNO=xx 
| OPTCD={fe 


x BLKSI 
f|M|Y|I|] 


ZE=xxxx 
R|L|U> 



created by providing another DD statement 
as follows: 



,. X 4 

^MOD not meaningful. CATLG allowed only 
if all areas are allocated with a single 
DD statement 

2 The DCB parameter should be the same for 
each DD statement 

Figure 28. DD Statement Parameters 

Applicable to Indexed Files 
Opened as Output 



If the programmer desires more control 
in the placement of the index area, he can 
subdivide storage before the data set is 



//ddname DD 

// 

// 

// 

// 

// DD 

// 

// 

// 

// 



DSNAi M -E=dsname ( INDEX) , X 

SPACE=(CYL, (no. of X 

cylinders) ), UNIT=unit, X 

VOLUME=SER=3 33333, X 
DCB=(DSORG=IS, . . . ) 

DSNAME=dsname( PRIME), X 

SPACE=(CYL, (no. of X 

cylinders) ). UNIT=unit, X 

VOLUME=SER=333333, X 
DISP=(disp) , DCB=*. ddname 



These DD statements will produce two 
separate areas: index and prime. Each 
area is on the same volume. 

If, along with more control of his 
index, the programmer wishes an independent 
overflow area, a third DD statement 
(OVFLOW) can be specified, as detailed 
earlier. The sequence will be: 

//ddname DD DSNAME=dsname ( INDEX ) , . . . 
// DD DSNAME=dsname ( PRIME ) , . . . 
// DD DSNAME=dsname ( OVFLOW) ,. .. 



These DD statements will produce three 
separate areas: index, prime, and 
overflow. 

Note that the OPTCD subparameter of the 
DCB parameter in each of the DD statements 
must specify an independent overflow area 
(OPTCD=I). All three areas reside on the 
same volume if so specified in the VOLUME 
parameter. 

Note: The sequence of the DSNAME parameter 
elements in all of the foregoing examples 
must be followed when placing the DD 
statements into the input stream, or an 
abnormal termination of the job will 
result. 

The example in Figure 29 defines a new 
indexed file that consists of three 
separate areas. All three areas reside on 
the same volume. The volume is on an IBM 
2311 Disk Storage Drive. 



//FILE DD DSNAME=ISM(INDEX),UNIT=2311,SPACE=(CYL, (1) ), 
// V0LUME=SER=111111, DCB= (DSORG=IS, OPTCD=I, . . . ) 

// DD DSNAME=ISM( PRIME), UNIT=2311,SPACE=( CYL, (5) ) f 
// V0LUME=SER=111111, DISP= ( , KEEP) , DCB=*. FILE 

// DD DSNAME=ISM( OVFLOW), UNIT=2311, SPACE= ( CYL, (1) ) , 
// V0LUME=SER=111111, DISP= ( , KEEP) , DCB=*. FILE 



Figure 29. Example of DD Statements for New Indexed Files 
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Catal oging Files ; 
cataloged if: 



An indexed file can be 



• All the areas of the file are allocated 
with a single DD statement. Such a 
file is cataloged in the usual manner 
by specifying the DISP parameter in the 
DD statement: 

DISP=(NEW, CATLG) 

• The areas are allocated with more than 
one DD statement, but all volumes are 
on the same type of device. Such a 
file is cataloged using the IEHPROGM 
utility program (see the publication 
IBM OS Utilities). 



An indexed file that is being created 
cannot be cataloged if its areas are on 
different device types. An existing 
indexed file cannot be cataloged through 
the specification of the CATLG subparameter 
of the DISP parameter in the DD statement. 

Note : The DD statement (s) defining a new 
or existing indexed file can appear in 
cataloged procedures. 

Calc ulating Space Requirements : To 
determine the number of cylinders required 
for an indexed file, the programmer must 
consider the number of records that will 
fit on a cylinder, the number of records 
that will be processed, and the amount of 
space required for indexes and overflow 
areas. In making the computations, 
additional space is also required for 
device overhead. 

Note: The allocation of space to the 
different areas of an indexed file is 
permanent. New allocations can be achieved 
only by recreating the file. It is, 
therefore, important to remember: 

• Unused space on the last cylinder on 
which data was written, in the prime 
area, is converted to an independent 
overflow area. Space allocated in 
excess of this cannot be released and 
will be wasted. 

• Excess space allocated to overflow or 
index areas cannot be released. 



Detailed information on space allocation 
can be found in the publication IBM_OS_Data 
Management Service s . 

Master Index : QISAM provides a master 
index facility to avoid inefficient serial 
searches of large cylinder indexes. The 
master index provides an index to the 
cylinder index. The programmer can specify 
with the DCB parameter in his DD 



statement(s) (see "DD Statement 
Requirements for Indexed Files" in 
"Creating Indexed Files") that a master 
index be built if the size of a cylinder 
index exceeds a certain number of tracks. 
Each entry in the master index points to a 
track of the cylinder index. If the size 
of the master index exceeds the number of 
tracks specified in the NTM parameter of 
the DD statement, the master index is 
automatically indexed by a higher level 
master index. Three such higher level 
master indexes can be constructed. 

COBOL C on si derations : When creating 
indexed files, the QISAM file processing 
technique is used. The following COBOL 
programming considerations should be noted: 

• RECORD KEY Clause. The RECORD KEY 
clause in the SELECT sentence of the 
Environment Division is required. It 
is used to specify the location of the 
key within the record itself. If the 
RECORD KEY clause has a PICTURE clause 
that specifies that the item is binary 
(COMPUTATIONAL), zero is the lowest 
number acceptable as the first record. 
A negative key is considered to be 
larger than a positive key; therefore, 
if a record is inserted into the file, 
a negative key would place the record 
after those records with positive keys. 

• Dummy Records. To reserve space for 
records to be added at a later time, 
when creating indexed files, dummy 
records can be written with the delete 
code (the figurative constant 

HIGH- VALUE) in the first byte. Dummy 
records and their deletion are 
described in "Using the WRITE 
Statement. " 

• Required and optional COBOL statements 
are summarized in Table 17. 



Reading or Updating Indexed Files 
Sequentia lly 



QISAM can be used to read or update an 
existing indexed file. Adding a record to 
an already existing file, however, can be 
done only with BISAM (see "Accessing an 
Indexed File Randomly"). 

When QISAM is used to read an input 
file, the READ statement makes available 
one logical record at a time in an 
ascending sequence determined by the record 
keys. Dummy records are not made 
available. If there are records in the 
overflow area, this sequence will not 
correspond exactly to the physical sequence 
of the records in the file. The file must 
have been created using QISAM. 
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When QISAM is used to update an 1-0 
file, the READ and REWRITE statements 
permit updating-in-place or deletion of a 
logical record. Logical records are read 
sequentially and may be either updated and 
rewritten, or rewritten unaltered, from the 
same area. Alteration of record length or 
insertion of new records is not permitted. 
A logical record is marked for deletion by 
moving the figurative constant HIGH-VALUE 
into the first character position of the 
record and then using the REWRITE 
statement. Records in the file that 
contain this deletion code are not made 
available on input. 

The discussion that follows is primarily 
concerned with indexed files that can be 
contained on a single volume. Additional 
information about processing existing 
indexed files accessed sequentially, 
including multivolume files, can be found 
in the publication IB M OS Job Co ntrol 
L ang u age Referenc e . 

Parameter Requirements : In the DD 
statement (s) indicating an existing indexed 
file, the following differences and 
requirements should be noted: 



Only one DD statement is needed to 
specify an existing file if all of the 
areas are on one volume. The following is 
an example of a DD statement that can be 
used when processing a single-volume QISAM 
file. 



//ddname DD DSNAME=dsname, X 

// DCB=(DSORG=IS, . . . ), X 

// UNIT=unit, DISP=OLD 



Further details about DD statements for 
existing single-volume and multivolume 
indexed files can be found in the 
publication IBM OS Job Contr ol Language 
Reference. 



Note: Figure 30 shows the parameters that 
may be used in a DD statement when 
processing indexed files opened as input or 
I-O. Additional information about indexed 
file structure is contained in the 
publication IBM OS Data Manageme nt 
Services. 



DCB 

The DSORG=IS subparameter must be 
specified, whereas the BUFNO 
subparameter is optional. The OPTCD 
field must not be specified again. 
Any OPTCD subparameter facilities that 
were specified when the file was 
created are in effect as long as the 
data set exists. For example, if the 
programmer specified the 
write-validity check option (OPTCD=W) 
when he created the file, the option 
is still in effect at the time of any 
subsequent WRITE statement. The 
BLKSIZE subparameter must not be 
specified. LRECL does not have to be 
specified if it already exists in the 
data set label. 

DSNAME (DSN) 

This parameter is written 
DSNAME=dsname. The element 
subparameters (INDEX, PRIME, OVFLOW) , 
must not be written. 



Reorganizing Files : As new records are 
added to an indexed file, chains of records 
may be created in the overflow area if one 
exists. The access time for retrieving 
records in an overflow area is greater than 
that required for retrieving records in the 
prime area. Input/output performance is, 
therefore, sharply reduced when many 
overflow records develop. For this reason, 
an indexed file can be reorganized as soon 
as the need becomes evident. The system 
maintains a set of statistics to assist the 
programmer when reorganization is desired. 
These statistics are maintained as fields 
of the file's data control block. Tney are 
made available when APPLY REORG-CRITERIA is 
specified. If these statistics arp 
desired, the OPTCD subparameter of the DCB 
parameter must have included the OPlCD=R 
parameter in each of the DD statements when 
the file was created. Additional 
information about reorganizing files is 
contained in the publication IBM OS Data 
Manag ement Services . 



DISP 

The first subparameter must be OLD. 
The second subparameter cannot be 
CATLG or UNCATLG (see "Cataloging 
Files" above for more information on 
cataloging indexed files). 

N ote : For further information about 
Indexed parameters, see "DD Statement 
Requirements for Indexed Files" in 
"Creating Indexed Files. " 



Sequential Retrieval Using the START 
Statement : For indexed INPUT and 1-0 
files, retrieval starts with the first 
nondummy record in the file. If the 
programmer wishes to begin processing at a 
point other than the beginning of the file, 
he can do so through the use of the START 
verb. When the START statement is used, 
the retrieval starts sequentially from the 
record specified in the NOMINAL KEY. 
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r t 1 

ddname | ddname used only for first DD 
statement of each file 



DSNAME | dsname 

I 

| Note : Element subparameter must 

| not be used. 



Device | Mass storage required 
-h 



UNIT 



| Applicable subparameter 

m^a. ^^c^q^ A -F GIT 



It! 



I cataloged. 
-+- 



SEP, A.FF | Restricted; see "Job Control 
j Procedures" 



4- 



VOLUME | Applicable subparameter s 



LABEL 



|SL 



SPACE | Not applicable 



SUBALLOC|Not applicable 



SPLIT | Not applicable 



DISP | [~, KEEP 

| OLD 3 - , PASS 
j \_, DELETE 

DCB | Required: DSORG=IS 

I 

| Optional: BUFNO=xxx (not allowed 
j for BISAM) 
| LRECL=xxx 
J. 



V- 



|*-CATLG UNCATLG not permitted. | 

L J 

Figure 30. DD Statement Parameters 

Applicable Indexed Files Opened 
as INPUT or 1-0 



constant HIGH-VALUE into the first 
character position of the record. The 
record is not physically deleted unless it 
is forced off its prime track by the 
insertion of a new record (see "Using the 
WRITE Statement" in "Accessing an Indexed 
File Randomly"), or if the file is 
reorganized. Records marked for deletion 
may be replaced (using BISAM) by new 
records containing equivalent keys. 
Execution of the READ statement in QISAM 
does not make available a record marked for 
deletion, whether the record has been 
physically deleted or not s Dummv records 
and deletion are discussed further in 
"Accessing an Indexed File Randomly. " 



-| Acc e ssing an Indexed File Randomly 



The file processing technique used for 
random retrieval of a logical record, the 
random updating of a logical record, and/or 
the random insertion of a record is BISAM 
(Basic Indexed Sequential Access Method) . 
When accessing an indexed file randomly, 
both NOMINAL KEY and RECORD KEY must be 
specified. The format of the NOMINAL KEY 
is described briefly below: 



r 1 

| Format | 

h ^ 

I I 

| NOMINAL KEY IS data-name | 

I I 

L J 



COBOL Considerations: When processing an 
already existing file with QISAM, the 
following COBOL programming considerations 
should be noted: 

• RECORD KEY Clause. The RECORD KEY 
always in the SELECT sentence of the 
Environment Division is required, just 
as it is when creating the file. Note 
other record key considerations under 
"Accessing an Indexed File Randomly. " 

• Delete Option. In order to keep the 
number of records in the overflow area 
to a minimum, and to eliminate 
unnecessary records, an existing record 
may be marked for deletion. This is 
done by moving the figurative 



Data-name may be any fixed-length 
Working Storage item from 1 through 255 
bytes in length. If it is part of a 
logical record, it must be at a fixed 
displacement from the beginning of that 
record description (see the publication IBM 
OS Full American National Standard C OBOL 
for additional information) . 



Since a RECORD KEY is used to identify a 
record to the system, the record keys 
associated with the logical records of the 
file may be thought of as a table of 
arguments. When a record is read or 
written, the contents of NOMINAL KEY is 
used as a search argument that is compared 
to the record keys of the file. 
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The following example illustrates the 
use of the NOMINAL KEY clause. 



ENVIRONMENT DIVISION. 



NOMINAL KEY IS NOM-KEY 
RECORD KEY IS REC-KEY. 



Notes; 

• Records with a key higher (or lower) 
tnan the current highest (or lowest) 
key of the file may oe added. 

• Whenever a WRITE statement is executed 
the contents of RECORD KEY and NOMINAL 
KEY must be identical. Except in the 
case of dummy records, this value must 
be unique in the file. 



DATA DIVISION. 

FILE SECTION. 

FD INDEXED-FILE 

LABEL RECORDS ARE STANDARD. 
01 REC-1. 

02 DELETE-CODE PIC X. 

02 REC-KEY PIC 9(5). 



Using th e R EWRITE Statemen t: If a record 
is to be updated, the indexed file should 
be opened as 1-0 and the REWRITE statement 
should be used. All REWRITE statements 
must be preceded by a READ statement. 
However, a READ statement can be followed 
by either a WRITE, REWRITE, or another 
READ. 



WORKING- STORAGE SECTION. 

77 NOM-KEY PIC 9(5). 



Because of their complementary use of 
the indexed file organization, much of the 
information discussed above for QISAM also 
applies to BISAM. Differences are noted 
below. 

U sin g the WRITE S t a te ment : The programmer 
can use the WRITE statement to add a new 
record into an indexed file. The record is 
added on the basis of the value specified 
in the NOMINAL KEY. The contents of the 
NOMINAL KEY are used to locate the two 
records in the file between which the new 
record is to be inserted. The records 
sought are those that have values less than 
and greater than the values in the nominal 
key field. Two methods can be used to add 
records. 

In the first method, the key to be added 
is a new key value. The record is inserted 
in place so that the sequence of the keys 
is maintained. If an overflow area exists, 
the insertion may cause records to be 
forced off the prime track into the 
overflow area. Dummy records forced off 
the track in this way are physically 
deleted and are not written in the overflow 
area. 

In the second method, the key of the 
record to be added has the same value as 
that of a known dummy record. If the dummy 
record has not been physically deleted, it 
is replaced by the new record. If it has 
been physically deleted, the record is 
inserted as though it had a new key value. 
If the key of the record to be added has 
the same value as a record other then a 
dummy record, an INVALID KEY condition will 
result. 



Note : Whenever a REWRITE statement is 
executed the value contained in NOMINAL KEY 
and RECORD KEY must be identical. 



Using the READ Statement: Records are 
retrieved on the basis of the value 
specified in tne NOMINAL KEY. If the key 
of a record marked for deletion is 
specified and the record has not been 
physically deleted, it will be produced. 
If the record has been physically deleted, 
the READ statement will cause an INVALID 
KEY condition and control will go to the 
INVALID KEY routine if specified. 

Note : Although the RECORD KEY clause must 
be specified, no value need be moved to the 
record key field before the execution of 
the READ statement. The search for the 
desired record is based on the contents of 
NOMINAL KEY. 



COBOL Considerations : When processing an 
indexed file randomly, the following COBOL 
programming considerations should be noted: 

• RECORD KEY Clause and NOMINAL KEY 

Clause. The RECORD KEY and NOMINAL KEY 
clauses in the SELECT sentence of the 
Environment Division are required. The 
RECORD KEY clause is used to specify 
the location of the key within the 
record itself. The NOMINAL KE3f is used 
as a search argument to locate the 
proper record, and must not be defined 
within the file being processed. Note 
that since a RECORD KEY is defined 
within a record, the contents of RECORD 
KEY are not available after a WRITE 
statement has been executed for that 
record. 
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Table 17. Indexed File Processing on Mass Storage Devices 



Data Management 
Techniques 


Access 
Method 


KEY 
Clauses 


OPEN 
Statement 


Access 
Verbs 


CLOSE 
Statement 


QISAM 


SEQUENTIAL 


RECORD 
NOMINAL 


INPUT 


READ [INTO] 
AT END 

START 
INVALID 
KEY 


[WITH LOCK] 


OUTPUT 


WRITE [FROM] 
INVALID KEY 


I-O 


READ [INTO] 

AT END 
START 

INVALID 

KEY 
REWRITE IFROMl 

INVALID KEY 


BISAM 


RANDOM 


RECORD 
NOMINAL 


INPUT 


READ [INTO] 
INVALID KEY 


[WITH LOCK] 


I-O 


READ [INTO] 
INVALID KEY 

WRITE [FROM] 
INVALID KEY 

REWRITE [FROM] 
INVALID KEY 



• TRACK-AREA Clause. Specifying the 
clause results in a considerable 
improvement in efficiency when a record 
is added to the file. If a record is 
added and the TRACK-AREA clause was not 
specified for the file, the contents of 
the NOMINAL KEY field are unpredictable 
after the WRITE statement is executed. 
In this case, the key must be 
reinitialized before the next WRITE 
statement is executed. 

• APPLY REORG-CRITERIA Clause. If the 
OPTCD=R parameter was specified on the 
DD card for an indexed file when it was 
created, the APPLY REORG-CRITERIA 
clause can be used to obtain the 
reorganization statistics when the file 
is closed. These statistics are moved 
from the data control block to the 
identifier specified in the clause when 
a CLOSE statement is executed for the 
file. 

• APPLY CORE-INDEX Clause. This clause 
specifies that the highest level index 
will reside in core storage during 
input/output operations. Otherwise, 
the index will be searched on the 
volume- and processing time will be 
longer. 

• Reguired and optional COBOL statements 
are summarized in Table 17. 



USING THE DD STATEMENT 



Each data set that is defined by a DD 
statement is either to be created, or has 
been previously created and is to be 



retrieved. In either case, the data set 
must have a disposition; for example, if 
the data set is being created, the 
disposition must indicate whether the data 
set is to be cataloged, kept, or deleted. 
Other DD parameters may simply indicate 
that the data set is in the input stream or 
that ultimately the data set is to be 
printed or punched. 

The following sections summarize the DD 
statement parameters and show examples for 
various uses of the DD statement. These 
sections include information about 
cataloging data sets and creating or 
referring to generation data groups; 
examples of cataloged data sets and 
partitioned data sets are included. For 
additional information about partitioned 
data sets see "Libraries. " Also see 
"Appendix I: Checklist for Job Control 
Procedures" for additional examples of the 
DD statement used in job control 
procedures. 



CREATING A DATA SET 



When creating a data set, the programmer 
ordinarily will be concerned with the 
following parameters: 

1. The data set name (DSNAME) parameter, 
which assigns a name to the data set 
being created. 

2. The unit (UNIT) parameter, which 
allows the programmer to state the 
type and quantity of input/output 
devices to be allocated for the data 
set. 
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3. The volume (VOLUME) parameter, which 
allows specification of the volume in 
which the data set is to reside. This 
parameter also gives instructions to 
the system about volume mounting. 



4. The space (SPACE), split cylinder 
(SPLIT), and suoallocation (SUBALLOC) 
parameters, for mass storage devices 
only, which permit the specification 
of the type and amount of space 
required to accommodate the data set. 

5. The label (LABEL) parameter, which 
specifies the type and some of the 
contents of the label associated with 
tne data set. 

6. The disposition (DISP) parameter, 
which indicates what is to be done 
with the data set by the system when 
the job step is completed. 



7. The DCB parameter, which allows the 
programmer to specify additional 
information to complete the DCB 
associated with the data set (see 
"User-Defined Files"). This allows 
additional information to be specified 
at execution time to complete the DCB 
constructed by the compiler for a data 
set defined in the source program. 

Figure 31 shows the subparameters that 
are frequently used in creating data sets. 
Additional subparameters are discussed in 
"Job Control Procedures. " 



Creating Unit RecordData Sets 



Data sets whose destination is a printer 
or card punch are created with the DD 
statement parameters UNIT and DCB. 



DSNAMEJ (dsname 

\ = ldsname( element)! 

IDSN ( j£&name 

/ (ssname (element)) 

UNIT=(name[,n] ) 

(volume) 

= < [PRIVATE] [, RETAIN] [ , volume-sequence-number] [, volume-count] 



(vol J 



, SER= (volume-serial-number [, volume-serial-number] . . . ) 

dsname 
*. ddname 
, REF= *.stepname. ddname 

*. stepname. procstep. ddname 



(TRK 
SPACE=( < CYL 



SPLIT=(n, 



( average-record-length 
[, directory-quantity] ) ) 
CYL 
average-record- length 



(NL ) 
LABEL=( [data-set sequence-number], )SL V 

)nsl( 
(sul; 



, (primary-quantity [ , secondary-quantity] 

[, (primary-quantity, [secondary-quantity])] 
7EXPDT=yyddd 



, RETPD=xxxx 



DISP=( 



NEW 



MOD 



, DELETE 
, KEEP 
, PASS 

, CATLG 



, DELETE 
, KEEP 
, CATLG 



DCB=(subparameter-list) 



Figure 31. DD Statement Parameters Frequently Used in Creating Data Sets 
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UNIT: Required. Code unit information 
using the 3-digit address (e.g., UNIT=00E) , 
the type (e.g., UNIT=1403), or the 
system-generated group name (e.g., 
UNIT=PRINTER) . 



DCB ; Required only if the data control 
block is not completed in the processing 
program. Valid DCB subparameters are 
listed in "Appendix C: Fields of the Data 
Control Block. " 



Crea t ing Data Sets on Magnetic Tape 



Tape data sets are created using 
combinations of the DD statement parameters 
UNIT, LABEL, DSNAME, DCB, VOLUME, and DISP. 



UNIT : Required, except when volumes are 
requested using VOLUME=REF. A unit can be 
assigned by specifying its address, type, 
or group name, or by requesting unit 
affinity with an earlier data set. 
Multiple output units and defer volume 
mounting can also be requested with this 
parameter. 

LABEL : Required when the tape has user 
labels or does not have standard labels, 
and when the data set does not reside first 



on the reel. It is also used to assign a 
retention period and password protection. 



DSNAME : Required for data sets that are to 
be cataloged or used by a later job. 



DCB : Required only when data control block 
information cannot be specified in COBOL. 
Usually, such attributes as the logical 
record length (LRECL) and buffering 
technique (BFTEK) will have been specified 
in the processing program. Other 
attributes, such as the OPTCD field and the 
tape recording technique (TRTCH), are more 
appropriately specified in the DD 
statement. Valid DCB subparameters are 
listed in "Appendix C: Fields of the Data 
Control Block. " 

VOLUME : Optional, this parameter is used 
to request specific volumes. If VOLUME=REF 
is specified, and the existing data sets on 
the specified volume(s) are to be saved, 
indicate the data set sequence number in 
the LABEL parameter. 

DISP : Required for data sets that are to 
be cataloged, passed, or kept. The 
programmer can specify conditional 
disposition as the third term in the DISP 
parameter to indicate how the data set is 
to be treated if the job step abnormally 
terminates. 



Creati ng Sequenti a l (BSA M or QSAM ) Data 
Sets o n Mass Stor ag e Devices 



Sequential data sets are created using 
combinations of the DD statements 
parameters UNIT, DSNAME, VOLUME, LABEL, 
DISP, DCB, and one of the space allocation 
parameters SPACE, SPLIT, or SUBALLOC. 



UNIT: Required, except when volumes are 
requested using VOLUME=REF or space is 
allocated using SPLIT or SUBALLOC. Assign 
a unit by specifying its address, type, or 
group name, or by requesting unit affinity. 



DSNAME: Required for all but temporary 
data sets. 



Label: Required to specify label type and 
to assign a retention period or password 
protection. 



(LRECL) and buffering technique (BFTEK) 
will have been specified in the processing 
program. Other attributes, such as the 
OPTCD field are more appropriately 
specified in the DD statement. Valid DCB 
subparameters are listed in "Appendix C: 
Fields of the Data Control Block. " 



VOLU ME : Optional. This parameter requests 
specific volumes (SER and REF) , specific 
volumes when the data set resides on more 
than one volume (seq #), multiple 
nonspecific volumes (volcount) , private 
volumes (PRIVATE) , or private volumes that 
are to remain mounted until the end of the 
job (RETAIN). 



DISP : Required for data sets that are to 
be cataloged, passed, or kept. The 
programmer can specify conditional 
disposition as the third term in the DISP 
parameter to indicate how the data set is 
to be treated if the job step abnormally 
terminates. 



DCB: Required only when data control block 
information is not completely specified in 
the processing program. Usually, such 
attributes as the logical record length 



SP ACE, SPLIT, SUBALLOC : One of these is 
required for all new mass storage data 
sets. 
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Creating Direct (BDAM) Data S ets 



Direct (BDAM) data sets are created 
using the same subset of DD statement 
parameters as sequential data sets, with 
the exception of the SPLIT parameter. 
Valid DCB subparameters for BDAM data sets 
are listed in "Appendix C: Fields of the 
Data Control Block." 



Creating In dexed (BISAM and QISA M) Data 
Sets 



Indexed (ISAM) data sets are created 
using combinations of the DD statement 
parameters UNIT, DSNAME, VOLUME, LABEL, 
DISP, DCB, and SPACE. The ISAM data sets 
occupy three areas of storage: an index 
a rea that contains master and cylinder 
indexes, a prime area that contains the 
data records and track indexes, and an 
optional o verflow are a to hold additional 
records when the prime area is exhausted. 
Detailed information on creating and 
retrieving indexed data sets is presented 
in "Appendix H: Creating and Retrieving 
Indexed Sequential Data Sets." 



output device. They are stored by the 
processing program on an intermediate mass 
storage device and later written on a 
system output device. In addition to the 
SYSOUT and DCB parameters, DD statements 
defining a data set of this type can also 
contain UNIT and SPACE parameters. All 
other parameters must be absent. 



SYSOUT: Required. The output class 
through which the data set is routed must 
be specified. Output classes are 
identified by a single alphanumeric 
character. (Do not use classes through 9 
except in cases where the other classes are 
not sufficient. ) 



DCB: Required only if complete data 
control block information has not been 
specified in the processing program. Data 
control block information is used when the 
data set is written on an intermediate mass 
storage volume and read by the output 
writer. However, the output writer* s own 
DCB attributes are used when the data set 
is written on the system output device. 
Valid DCB parameters are listed in 
"Appendix C: Fields of the Data Control 
Block. " 



C re a ting Data Sets in the Output Str eam 



New data sets can be written on a system 
output device in much the same way as 
messages. When using a sequential 
scheduler, a data set is directed to the 
output stream with the SYSOUT and DCB 
parameters. 

S YSOUT : Required. The output class 
through which the data set is routed must 
be specified. Output classes are 
identified by a single alphanumeric 
character. 

DCB: Required only if complete data 
control block information has not been 
specified in the processing program. 

When using a priority scheduler, data 
sets are not routed directly to a system 



UNIT: Optional. An intermediate mass 
storage device is assigned if UNIT is 
specified. A default device is assigned if 
this parameter is omitted. 

SPACE : Optional. Estimate the amount of 
mass storage space required. A default 
estimate is assumed if this parameter is 
omitted. 

Note : When a Direct SYSOUT Writer is used, 
the priority scheduler functions as a 
sequential scheduler. The SYSOUT data sets 
of the particular output class from any of 
the elegible job classes are not stored on 
an intermediate storage device, but are 
written directly to the system output 
device. When Direct SYSOUT Writer is used, 
all the parameters on the DD card are 
ignored. For detailed information on 
Direct SYSOUT Writer, see the publication 
IBM OS Operator 1 s Reference, Order 
NO. GC28-6691. 
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Examples of D P Statements Used To Create Data Sets 

The following examples show various ways of specifying DD statements 
for data sets that are to be created. In general, the number of 
parameters and subparameters that are specified depend on the 
disposition of the data set at the end of the job step. If a data set 
is used only in the job step in which it is created and is deleted at 
the end of the job step, a minimum number of parameters are required. 
However, if the data set is to be cataloged, more parameters should be 
specified. 



Example 1 ; Creating a data set for the current job step only. 
//SYSUTl DD UNIT=SYSDA, SPACE=(TRK, (50,10) ) 

This example shows the basic required DD statement for creating and 
storing a data set on a mass storage device. The UNIT parameter is 
required unless the unit information is available from another source. 
If the data set were to be stored on a unit record or a tape device, the 
SPACE parameter would not be needed. The operating system assigns a 
temporary data set name and assumes a disposition of (NEW, DELETE). 



Example 2 : Creating a data set that is used only for the current job. 

//SYSLIN DD DSNAME=&STEMP,DISP= (MOD, PASS), UNIT=SYSSQ, X 

// SPACE=(TRK, (50) ) 

This example shows a DD statement that creates a data set for use in 
more tnan one step of a job. The system assigns a unique symbol for the 
name, and this same symbol is substituted for each recurrence of the 
££TEMP name within the job. The data set is allocated space on any 
available mass storage or tape device. If a tape device is selected, 
the SPACE parameter is ignored. The disposition specifies that the data 
set is either new or is to be added to (MOD), and is to be passed to the 
next job step (PASS). This DD statement can be used for specifying the 
data set that is created as output from the compiler and that is to be 
used as input to the linkage editor. 3y specifying MOD, separately 
compiled object modules can be placed in sequence in the same data set. 

Note : If MOD is specified for a data set that does not already exist, 
the job may be abnormally terminated when a volume reference name, a 
volume serial number, or the disposition CATLG is specified or when the 
dsname is indicated by a backwards reference. 
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Example 3 : Creating a data set that is to be kept but not cataloged. 

//TEMPFILE DD DSN=FILEA, DISP= < , KEEP) ,SPACE=(TRK, (30, 10) ), X 

// UNIT=DIRECT, VOL= ( , RETAIN, SER=AA70 ) 

The example shows a DD statement that creates a data set that is kept 
but not cataloged. The data set name is FILEA. The disposition (,KEEP) 
specifies that the data set is being created in this job step and is to 
be kept. It is kept until a disposition of DELETE is specified on 
another DD statement. The KEEP parameter implies that the volume is to 
be treated as private. Private implies that the volume is unloaded at 
the end of the job step but because RETAIN is specified, the volume is 
to remain mounted until the end of the job unless another reference to 
it is encountered. The DIRECT parameter is a hypothetical device class, 
containing only mass storage devices. The volume with serial number 
AA70, mounted on a device in this class, is assigned to the data set. 
Space for the data set is allocated as specified in the SPACE parameter. 
The data set has standard labels since it is on a mass storage volume. 

If the volume serial number were not specified in the foregoing 
example, the system would allocate space in an available nonprivate 
volume. Because KEEP is specified, the volume becomes private. 
(Another data set cannot be stored on a private volume unless its volume 
serial number is specified or affinity with a data set on the volume is 
stated. ) The volume serial number of the volume assigned, if 
applicable, is included in the disposition message for the data set. 
Disposition messages are messages from the job scheduler, generated at 
the end of the job step. 



Example 4 : Creating a data set and cataloging it. 

//DDNAMEA DD DSNAME=INVENT. PARTS, DISP= (NEW, CATLG) , X 

// LABEL=( # ,EXPDT=71031) ,UNIT=DACLASS, X 

// V0LUME=(,REF=*.STEP1.DD1), X 

// SPACE=(CYL, (5, 1), ,CONTIG) 

This example shows a DD statement that creates a data set named 
INVENT. PARTS and catalogs it in the previously created system catalog. 
The data set is to occupy the same volume as the data set referred to in 
the DD statement named DDl occurring in the job step named STEP1. The 
UNIT parameter is ignored since REF is specified. Five cylinders are 
allocated to the data set, and if this space is exhausted, more space is 
allocated, one cylinder at a time. The five cylinders are to be 
contiguous. The disposition (CATLG), implies that the volume is to be 
private. The INVENT. PARTS is to have standard labels. The expiration 
date is the 31st day of 1971. 



Example 5 : Adding a member to a previously created library. 
//SYSLMOD DD DSNAME=SYSl. LINKLIB (INVENT) , DISP=OLD 

This DD statement adds a member named INVENT to the link library 
(SYS1. LINKLIB) . When a member is added to a previously created data 
set, OLD should be specified. The member INVENT takes on the 
disposition of the library. 
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Example 6 : Creating a library and its first member. 

//SYSLMOD DD DSNAME=USERLIB (MYPROG) , DISP= ( , CATLG) , X 

// SPACE=(TRK, (50, 30,3) ) , UNIT=2311, VOLUME=SER=llllll 

This DD statement creates a library, USERLIB, and places a member, 
MYPROG, in it. The disposition (, CATLG) indicates that the data set is 
being created in this job step (NEW is the default condition for the 
DISP parameter and is indicated by the comma) and is to be cataloged. 
The data set is to have standard labels. Space is allocated for the 
data set in a volume on a mass storage device that is an IBM 2311 unit. 
Initially, 50 tracks are allocated to the data set, but when this space 
is exhausted, more tracks are added, 30 at a time. The SPACE parameter 
must be specified when the library is created, and it must include 
allocation of space for the directory. SPACE cannot be specified when 
new members are added. If additional space is required when new members 
are added, the secondary allocation, if specified, will be used. Three 
256-byte records are to be used for the directory. The volume serial 
number of the volume on which the library is to reside, is 111111. 



Example 7 : Replacing a member of an existing library. 
//SYSLMOD DD DSNAME=MYLIB (CASE3) , DISP=OLD 

This DD statement replaces the member named CASE3 with a new member 

with the same name. if the named member does not exist in the library, 

the member is added as a new member. In the foregoing example, the 
library is cataloged. 



Example 8 : Creating and adding a member to a library used only for the 
current job. 

//SYSLMOD DD DSNAME=S&USERLIB (MYPROG) , DISP= (, PASS) , UNIT=SYSDA, X 
// SPACE=(TRK, (50, , 1) ) 

This DD statement creates and adds a member to a temporary library. 
It is similar to the DD statement shown in Example 6, except that a 
temporary name is used and the data set is not cataloged nor kept but is 
simply passed to the next job step. Since the data set is to be used 
only for this one job, it is not necessary to specify VOLUME and LABEL 
information. This statement can be used for a linkage edit job step in 
which the module is to be passed to the next step. 

Note : If DISP=(, DELETE) is specified for a library, the entire library 
will be deleted. 



User File Processing 127 



RETRIEVING PREVIOUSLY CREATED DATA SETS 



The parameters that must be specified in 
a DD statement to retrieve a previously 
created data set depend on the information 
that is available to the system about the 
data set. For example, 



1. If a data set on a magnetic-tape or 
mass storage volume was created and 
cataloged in a previous job or job 
step, all information for the data 
set, such as volume, space, etc. , is 
stored in the catalog and data set 
label. This information need not be 
repeated. Only the dsname and 
disposition parameters need be 
specified. 



2. If the data set was created and kept 
in a previous job but has not been 
cataloged, information concerning the 
data set, such as space, record 
format, etc., is stored in the data 
set label. However, the unit and 
volume information must be specified 
unless available elsewhere. 



3. If the data set was created in the 

current job step, or in a previous job 
step in the current job, the 
information in the previous DD 
statement is available to the system 
and is accessible by referring to the 
previous DD statement. Only the 
dsname and disposition parameters need 
be specified. 



Note: A programmer may wish to change the 
previous disposition of a data set. For 
example, if KEEP was specified when the 
data set was created, the DD statement that 
retrieves the data set may change the 
disposition by specifying CATLG. 



Figure 32 shows the parameters that are 
used to retrieve previously created data 
sets. 



Retrieving Catalog ed Data Sets 



Input data sets, assigned a disposition 
of CATLG or cataloged by the IEHPROGM 
utility program, are retrieved using the DD 
statement parameters DSNAME, DISP, LABEL, 
and DCB. The device type, volume serial 
number, and data set sequence number (if 
tape) are stored in the catalog. 
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Figure 32. Parameters Frequently Used in 
Retrieving Previously Created 
Data Sets 



DSNAM E: Required. The data set must be 
identified by its cataloged name. If the 
catalog contains more than one index level, 
the data set name must be fully qualified. 

DISP: Required. The status (OLD or SHR) 
of the data set must be given and an 
indication made as to how it is to be 
treated after its use, unless it is to 
remain cataloged. The programmer can 
specify as the third term in the DISP 
parameter a conditional disposition to 
indicate how the data set is to be treated 
if the job step abnormally terminates. 

LABEL: Required only if the data set does 
not have a standard label. 

DCB : Required only if complete data 
control block information is not specified 
by the processing program and the data set 
label. To save recoding time, DCB 
attributes can be copied from an existing 
DCB parameter and modified if necessary. 
Valid DCB subparameters are listed in 
"Appendix C: Fields of the Data Control 
Block. " 

Note: In addition to the disposition 
UNCATLG, a cataloged data set can be passed 
to a later step (PASS) or deleted (DELETE). 
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Retrieving Noncatalo qed (KEEP) D ata Sets 



Input data sets that were assigned a 
disposition of KEEP are retrieved by their 
tabulated name and location, using the DD 
statement parameters DSNAME, UNIT, VOLUME, 
DISP, LABEL, and DCB. 



DSNAME: Required. The data set must be 
identified by the name assigned to it when 
it was created. 



UNIT: Required, unless VOLUME=REF is used. 
The unit must be identified by its address, 
type, or group name. If the data set 
requires more than one unit, give the 
number of units. Deferred volume mounting 
and unit separation can be requested with 
this parameter. 

VOLUME: Required. The volume (s) must be 
identified with serial numbers or, if the 
data set was retrieved earlier in the same 
job, with VOLUME=REF. If the volume is to 
be PRIVATE, it must be so designated. If a 
private volume is to remain mounted until a 
later job step uses it, RETAIN should be 
designated. 

DISP : Required. The status (OLD or SHR) 
of the data set must be given and an 
indication made as to how it is to be 
treated after its use. The programmer can 
specify conditional disposition as the 
third term in the DISP parameter to 
indicate how the data set is to be treated 
if the job step abnormally terminates. 

LABE L: Required if the data set does not 
have a standard label. If the data set 
resides with others on tape, its sequence 
number must be given. 

DCB: Required for all indexed data sets. 
Otherwise, required only if complete data 
control block information is not supplied 
by the processing program and the data set 
label. To save recoding time, copy DCB 
attributes from an existing DCB parameter, 
and modify them if necessary. Valid DCB 
subparameters are listed in Appendix C. 



DS NAME : Required. The original data set 
must be identified by either its name or 
the DD statement reference term 
♦.stepname. ddname. If the original DD 
statement occurs in a cataloged procedure, 
the procedure stepname must be included in 
the reference term. 

DISP : Required. The data set must be 
identified as OLD, and an indication made 
as to how it is to be treated after its 
use. The programmer can specify 
conditional disposition as the third term 
in the DISP parameter to indicate how the 
data set is to be treated if the job step 
abnormally terminates. 

UNIT : Required only if more than one unit 
is allocated to the data set. 



Extending Da ta Sets with Additional Output 



A processing program can extend an 
existing data set by adding records to it 
instead of reading it as input. Such a 
data set is retrieved using the same 
subsets of DD statement parameters 
described under the preceding three topics, 
depending on whether it was cataloged, 
kept, or passed when created. In each 
case, however, the DISP parameter must 
indicate a status of MOD. When MOD is 
specified, the system positions the 
appropriate read/write head after the last 
record in the data set. If a disposition 
of CATLG for an extended data set that is 
already cataloged is indicated, the system 
updates the catalog to reflect any new 
volumes caused by the extension. 

When extending a multi volume data set 
where number of volumes might exceed the 
number of units used, the programmer should 
either specify a volume count or deferred 
mounting as part of the volume information. 
This ensures data set extension to new 
volumes. 



Retrieving Data through an Input Stream 



Retrieving Pa ssed Data Sets 



Input data sets used in a previous job 
step and passed are retrieved using the DD 
statement parameters DSNAME, DISP, and 
UNIT. The data set's unit type, volume 
location, and label information remain 
available to the system from the original 
DD statement. 



Data sets in the form of decks of cards 
or groups of card images can be introduced 
to the system through an input stream by 
interspersing them with control statements. 
To define a data set in the input stream, 
mark the beginning of the data set with a 
DD statement and the end with a delimiter 
statement. The DD statement must contain 
one of the parameters * or DATA. Use DATA 
if the data set contains job control 
statements and an * if it does not. Two 
DCB subparameters can also be coded when 
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defining a data set in the input stream. 
In systems with MFT or MVT, data in the 
input stream is temporarily transferred to 
a mass storage device. The DCB 
subparameters BLKSIZE and BUFNO allow 
blocking of this data as it is placed on 
the mass storage device. 



• The records must be unblocked, and 
80-characters in length. 



The characters in the records must be 
coded in BCD or EBCDIC. 



Notes : 

When using a seguential scheduler: 

• The input stream must be on a card 
reader or magnetic tape. 

• Each job step and procedure step can be 
associated with only one data set in 
the input stream. 



when using a priority scheduler: 

• The input stream can be on any device 
supported by QSAM. 

• Each job step and procedure step can be 
associated with several data sets in an 
input stream. All such data sets 
except the first in the job must be 
preceded by DD * or DD DATA statements. 



• The DD statement must be the last in 
the job step or procedure step. 



The characters in the records must be 
coded in BCD or EBCDIC. 
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Examples of DP St atements Used to Retr ieve Dat a Sets 



Example 1 ; Retrieving a cataloged data set. 

//CALC DD DSNAME=PROCESS,DISP=(OLD, PASS, KEEP) 

This DD statement retrieves a cataloged data set named PROCESS. No 
UNIT or VOLUME information is needed. Since PASS is specified, the 
volume in which the data set is written is retained at the end of the 
job step. PASS implies that a later job step will refer to the data 
set. The last step in the job referring to the data set should specify 
the final disposition. If no other DD statement refers to the data set, 
it is assumed that the status of the data set is as it existed before 
this job. In the event of an abnormal termination, the KEEP disposition 
explicitly states the disposition of the data set. 



Example 2 : Retrieving a data set that was kept but not cataloged. 

//TEMPFILE DD DSNAME=FILEA, UNIT=DIRECT, VOLUME=SER=AA70, DISP=OLD 

This DD statement retrieves a kept data set named FILEA. (This data 
set is created by the DD statement shown in Example 3 for creating data 
sets. ) The data set resides on a device in a hypothetical device class, 
DIRECT. The volume serial number is AA70. 



Example 3 ; Referring to a data set in a previous job step. 

//SAMPLE JOB 

//STEP1 EXEC PGM=IKFCBLOO,PARM=DECK 



//SYSLIN DD DSNAME=ALPHA, DISP=( NEW, PASS) , UNIT=SYSSQ 

//STEP2 EXEC PGM=IEWL 

//SYSLIN DD *. STEP1. SYSLIN, DISP=( OLD, DELETE) 

The DD statement SYSLIN in STEP2 refers to the data set defined in 
the DD statement SYSLIN in STEP1. 



Example 4 : Retrieving a member of a library. 

//BANKING DD DSNAME=PAYROLL ( HOURLY) , DISP=OLD 

The DD statement retrieves a member, HOURLY, from a cataloged 
library, PAYROLL. 
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DD_ STATEMENTS, THAT SPECIFY UNIT RFCORD 
DEVICES 



A DD statement may simply indicate that 
data follows in the input stream or that 
the data set is to be punched or printed. 
Figure 33 shows the parameters of special 
interest for these purposes. 



Example 3: Specifying a card punch. 

//SYSPUNCH DD SYSOUT=B 

B is the standard device class for punch 
devices. 



CATALOGING A DATA SET 



JDATAJ 
SYSOUT=A 
UNIT=name 
DCB= ( subparameters ) 

|. 1 

Note: The DCB parameter can be 
specified, where permissible, for data 
sets on unit record devices. For 
example, it can be specified for 
compiler data sets (other than SYSUT1, 
SYSUT2, SYSUT3, and SYSUT4) and data 
sets specified by the DD statements 
required for the ACCEPT and DISPLAY 
statements, when any of these data sets 
are assigned to unit-record devices. 



Figure 33. 



Parameters Used To Specify 
Unit Record Devices 



Example 1: 
reader. 



Specifying data in the card 



A data set is cataloged whenever CATLG 
is specified in the DISP parameter of the 
DD statement that creates or uses it. This 
means that the name and volume 
identification for the data set are placed 
in a system index called the catalog. (See 
"Processing with QISAM" in the section 
"Execution Time Data Set Requirements" for 
information about cataloging indexed data 
sets. I The information stored in the 
catalog is always available. to the system; 
consequently, only the data set name and 
disposition need be specified in subsequent 
DD statements that retrieve the data set. 
See Example 4 in "Creating Data Sets, " and 
Example 1 in "Retrieving Data Sets. " 

If DELETE is specified for a cataloged 
data set, any reference to the data set in 
the catalog is deleted unless the DD 
statement containing DELETE retrieves the 
data set in some way other than by using 
the catalog. If UNCATLG is specified for a 
cataloged data set, only the reference in 
the catalog is deleted; the data set itself 
is not deleted. 

Note: A "cataloged data set" should not be 
confused with a "cataloged procedure" (see 
"Using the Cataloged Procedures"). 



//SYSIN 



DD * 



GENERATION DATA GROUPS 



The asterisk indicates that data follows 
in the input stream. This statement must 
be the last DD statement for the job step. 
The data must be followed by a delimiter 
statement. 



E xample 2 : Specifying a printer data set. 



//SYSPRINT DD SYSOUT=A 



SYSOUT is the system output parameter; A 
is the standard device class for printer 
data sets. 



It is sometimes convenient to save data 
sets as elements or generations of a 
generation data group (DSNAME=dsname 
(element)). A generati on data gro up is a 
collection of successive, historically 
related data sets. Identification of data 
sets that are elements of a generation data 
group is based upon the time the data set 
is added as an element. That is, a 
generation number is attached to the 
generation data group name to refer to a 
particular element. The name of each 
element is the same, but the generation 
number changes as elements are added or 
deleted. The most recent element is 0, the 
element added previous to is -1, the 
element added previous to -1 is -2, etc. A 
generation data group must always be 
cataloged. 
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For example, a data group named PAYROLL 
might be used for a weekly payroll. The 
elements of the group are: 

PAYROLL(O) 
PAYROLL (-1) 
PAYROLL (-2) 

where PAYROLL(O) is the data set that 
contains the information for the most 
current weekly payroll, and is the most 
recent addition to the group. 

When a new element is added, it is 
called element (+n), where n is an integer 
greater than 0. For example, when adding a 
new element to the weekly payroll, the DD 
statement defines the data set to be added 
as PAYROLL(+l); at the end of the job the 
system changes its name to PAYROLL (0). The 
element that was PAYROLL(O) at the 
beginning of the job becomes PAYROLL (-1) at 
the end of the job, and so on. 

If more than one element is being added 
in the same job, the first is given the 
number (+1), the next (+2) and so on. 



each other. Including all simple names and 
periods, the length of a data set name must 
not exceed 44 characters. Thus, a maximum 
of 21 qualification levels is possible for 
a data set name. 

Programmers should not use fully 
qualified data set names that begin with 
the letters SYS and that also have a P as 
the' nineteenth character of the name. 
Under certain conditions, data sets with 
the above characteristics will be deleted. 



ADDITIONAL FILE PROCESSING INFORMATION 



The following topics are discussed in 
this section: the data control block, 
error processing for COBOL files, and 
volume and data set labels. 

More information about input/output 
processing is contained in the publication 
IBM OS Data Manag ement . Services . 



NAMING DATA SETS 



DATA CONTROL BLOCK 



Each data set must be given a name. The 
name can consist of alphanumeric characters 
and the special characters, hyphen and the 
+0 (12-0 multipunch) . The first character 
of the name must be alphabetic. The name 
can be assigned by the system, it can be 
given a temporary name, or it can be given 
a user-assigned name. If no name is 
specified on the DD statement that creates 
the data set, the system assigns to the 
data set a unique name for the job step. 
If a data set is used only for the duration 
of one job, it can be given a temporary 
name (DSNAME=S£name) . If a data set is to 
be kept but not cataloged, it can be given 
a simple name. If the data set is to be 
cataloged it should be given a fully 
qualified data set name. The fully 
qualified data set name is a series of one 
or more simple names joined together so 
that each represents a level of 
qualification. For example, the data set 
name DEPT999* SMITH* DATA3 is composed of 
three simple names that are separated by 
periods to indicate a hierarchy of names. 
Starting from the left, each simple name 
indicates an index or directory within 
which the next simple name is a unique 
entry. The rightmost name identifies the 
actual location of the data set. 

Each simple name consists of one to 
eight characters, the first of which must 
be alphabetic. The special character 
period (.) separates simple names from 



Each data set is described to the 
operating system by a data control block 
(DCB) . A data control block consists of a 
group of contiguous fields that provide 
information about the data set to the 
system for scheduling and executing 
input/output operations. The fields 
describe the characteristics of the data 
set (e.g., data set organization) and its 
processing requirements (e.g., whether the 
data set is to be read or written) . The 
COBOL compiler creates a skeleton DCB for 
each data set and inserts pertinent 
information specified in the Environment 
Division, FD entry, and input/output 
statements in the source program. The DCB 
for each file is part of the object module 
that is generated. Subsequently, other 
sources can be used to enter information 
into the data control block fields. The 
process of filling in the data control 
block is completed at execution time. 

Additional information that completes 
the DCB at execution time may come from the 
DD statement for the data set and, in 
certain instances, from the data set label 
when the file is opened. 



0Y§££i^iH2_DCB_Fields 



Once a field in the DCB is filled in by 
the COBOL compiler, it cannot be overridden 
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by a DD statement or a data set label. For 
example, if the buffering factor for a data 
set is specified in the COBOL source 
program by the RESERVE clause, it cannot be 
overridden by a DD statement. In the same 
way, information from the DD statement 
cannot be overridden by information 
included in the data set label. 



of the DCB macro instruction for the 
appropriate file processing technique in 
the publication I BM OS Data Manage m ent 
Services. 



ERROR PROCESSING FOR COBOL FILES 



I dentify ing DCB Informa tion 



System Error Recovery 



The links between the DCB, DD statement, 
data set label, and input/output statements 
are the filename, the system name in the 
ASSIGN clause of the SELECT statement, the 
ddname of the system-name, and the dsname 
(Figure 3U>. 

1. The filename specified in the SELECT 
statement and in the FD entry of the 
COBOL source program is the name 
associated with the DCB. 

2. Part of the system-name specified in 
the ASSIGN clause of the source 
program is the ddname link to the DD 
statement. This name is placed in the 

DCB. 

3. The dsname specified in the DD 
statement is the link to the physical 
data set. 

The fields of the data control block are 
described in the tables in Appendix C. 
They identify those fields for which 
information must be supplied by the source 
proqram, by a DD statement, or by the data 
set label. For further information about 
the data control block, see the discussion 



During the processing of a COBOL file, 
data transmission to or from an 
input/output device may not be successful 
the first time it is attempted. If it is 
not successful, standard error recovery 
routines, provided by the operating system, 
attempt to clear the failure and allow the 
program to continue uninterrupted. 

If an input/output error cannot be 
corrected by the system, an abnormal 
termination (ABEND) of the program may 
occur unless the programmer has specified 
some means of error analysis. Error 
processing routines initiated by the 
programmer are discussed in the following 
paragraphs, and in "Appendix G: 
Input/Output Error Conditions. " 

For sequential files, the programmer can 
specify a DD statement option (EROPT) that 
specifies the type of action to be taken by 
the system if an error occurs. This option 
can be specified whether or not a 
declarative is written. If a declarative 
is specified, the DD statement option is 
executed when a normal exit is taken from 
the declarative. See "Accessing a Standard 
Sequential File" for further information. 



r 1 r 

| SELECT | | Data Set 
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Figure 34. Links between the SELECT Statement, the DD Statement, the Data Set Label, and 
the Input/Output Statements 
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INVALID KEY Option 



INVALID KEY errors may occur for files 
accessed randomly, or for output files 
accessed sequentially. A test to determine 
these errors may be made by using the 
INVALID KEY option of the READ, WRITE, 
REWRITE, or START verb. 

N ote : Secondary space allocation must be 
specified when the INVALID KEY option is 
used in a WRITE statement for QSAM and 
BSAM. 



specified, the program may terminate 
abnormally or may continue executing with 
incorrect data. Table 18 is a generalized 
summary of the means available for recovery 
from an invalid key condition or an 
input/output error. Table 19 lists the 
error processing facilities available for 
each type of file organization. The 
following discussion summarizes the action 
taken by each facility for each type. For 
further information on the USE AFTER ERROR 
option, see the publication IBM_OS_Full 
American National Standard COBOL. 



USE AFTER ERROR 



)tion 



The programmer may specify the USE AFTER 
ERROR option in the declarative section of 
the Procedure Division to determine the 
type of the input/output error. With the 
USE AFTER ERROR option, the programmer can 
pass control to an error-processing routine 
to investigate the nature of the error. If 
the GIVING option of the USE AFTER ERROR 
declarative is specified, data-name-1 will 
contain information about the error 
condition. Data-name-2, if specified, will 
contain the block in error if the last 
input/output operation was a read. If the 
file was opened as output, data-name-2 in 
the GIVING option cannot be referenced. 

Data-name-2 of the GIVING option 
contains valid data only if data was 
actually transferred on the last 
input/output operation. For example, if 
the declarative is entered after execution 
of a START verb for a QISAM file on which 
no INVALID KEY option was present, an 
attempt to access data-name-2 results in an 
abnormal termination, because no transfer 
of data has taken place. Hence, the user 
should specify data-name-2 only within 
declaratives associated with READ 
statements. Otherwise, the user should 
define data-name-2 within the linkage 
section, so the user can examine 
data-name-1 and decide whether data-name-2 
will be helpful. 

Either or both the INVALID KEY clause 
and the USE AFTER ERROR declarative may be 
specified for a file. If both have been 
specified and an INVALID KEY error occurs, 
the imperative-statement specified in the 
INVALID KEY option will be executed. If 
both have been specified and any other type 
of input/output error occurs, the USE AFTER 
ERROR declarative will be entered. If an 
error occurs and neither has been 



STANDARD SEQUENTIAL 

• Operating System: If the error cannot 
be corrected (read only) , the program 
will ABEND in the absence of a DD 
statement option, USE AFTER STANDARD 
ERROR declarative, or INVALID KEY 
option. If both the DD statement 
option and USE section are specified, 
the control program will execute the 
USE declarative first and then the DD 
option if normal exit is taken from the 
declarative section. If no EROPT 
subparameter is indicated, or if ABS is 
specified and a USE AFTER STANDARD 
ERROR declarative exists, the 
declarative will receive control. 
After a normal exit, the job will 
abnormally terminate. 

• DD Statement Option: The EROPT 
subparameter in the DCB parameter 
specifies one of three actions: accept 
the error block (ACC) , skip the error 
block (SKP), or terminate the job 
(ABE). 

• INVALID KEY: A transfer of control to 
the procedure indicated in the INVALID 
KEY phrase occurs if additional space 
cannot be allocated to write the record 
requested. This condition occurs when 
either no more space is available or 16 
extents have already been allocated on 
the last volume assigned to the data 
set. The transfer of control occurs 
only if a secondary-quantity is 
specified in the DD statement SPACE, 
SPLIT, or 3UBALLOC parameter. If no 
secondary-quantity is specified, the 
primary-quantity is assumed to be the 
exact amount of space required for the 
data set, and any attempt to write a 
record beyond the storage allocated 
causes the program to end abnormally. 
When an INVALID KEY error occurs, the 
file can be closed so that it may 
subsquently be reopened for retrieval 
as INPUT or 1-0. 



User File Processing 135 



Table 18. Recovery from an Invalid Key Condition or from an Input/Output Error 
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Table 19. Input/Output Error Processing Facilities 
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Holds only for WRITE. 

Error cannot be caused by an invalid key. 

No system error processing facility is available. If errors occur, they are 

ignored and processing continues, unless a programmer-specified error processing 

routine is indicated. 



• USE AFTER STANDARD ERROR: The 
programmer may specify this option in 
order to display the cause of the 
error. Control goes to the declarative 
section; the programmer can then 
display a message indicating the error 
and execute his DD statement option on 
a normal exit from the declarative 
section. 

INDEXED (RANDOM) 

• INVALID KEY: If the error is caused by 
an invalid key, recovery is possible. 



If the error is not an invalid key and 
the USE AFTER ERROR option is not 
specified, the program is terminated. 

USE AFTER STANDARD ERROR: Control goes 
to the declarative section. The 
programmer can check the error type in 
the section by specifying data-name- 1 
in the GIVING option. If the error is 
caused by a key error or the "no space 
found" condition, recovery is possible. 
On a READ error, the block can be 
skipped by executing additional READ 
statements. If the error persists 



L36 



(more bad READ statements than the 
blocking factor), processing is limited 
to a CLOSE statement. Any other error 
cannot be corrected. The program may 
continue executing, but processing of 
the file is limited to CLOSE. If the 
programmer closes the file, he may do 
so in either the declarative section or 
in the main body of his program. 



INDEXED (SEQUENTIAL) 

A. WRITE (load mode) 

• Operating System: If the error 
cannot be corrected, the program 
will ABEND unless an error 
processing option is specified. 

• INVALID KEY: If the error is caused 
by an invalid key, recovery is 
possible. (The programmer may 
attempt to reconstruct the key and 
retry the operation, or may bypass 
the error record. ) 

• USE AFTER STANDARD ERROR: Control 
goes to the declarative section. 
The programmer can check the error 
type in the section by specifying 
data-name-1 in the GIVING option. 
If the error is the result of a key 
error, recovery is possible. If the 
error is not a key error, the error 
cannot be corrected. The program 
may continue executing, but 
processing of the file is limited to 
CLOSE. If the programmer closes the 
file, he may do so in either the 
declarative section or in the main 
body of his program. 

B. READ, REWRITE (scan mode) 

• Operating System: If the error 
cannot be corrected, the program 
will ABEND unless an error 
processing option is specified. 

• INVALID KEY: The error cannot be 
caused by an invalid key. A source 
program coding error is implied and 
a compiler diagnostic message is 
generated. 

• USE AFTER STANDARD ERROR: The 
programmer may specify this option 
in order to display the cause of the 
error. Control goes to the 
declarative section. The programmer 
can check the error type in the 
section by specifying data-name-1 in 
the GIVING option. Since the error 
cannot be caused by an invalid key, 
processing of the file is limited to 
CLOSE. If the programmer elects to 
close the file, he may do so in 



either the declarative section or in 
the main body of his program. 



DIRECT or RELATIVE (RANDOM) 

• Operating System: If the error 
cannot be corrected, the program 
will ABEND unless an error 
processing option is specified. 

• INVALID KEY: If the error is caused 
by an invalid key, recovery is 
possible. 

• USE AFTER STANDARD ERROR: Control 
goes to the declarative section. 
The programmer can check the error 
type in the section by specifying 
data-name-1 in the GIVING option. 
If the error is the result of a key 
error or the "no space found within 
the search limit" condition, 
recovery is possible. Any other 
error cannot be corrected. The 
program may continue executing, but 
processing of the file is limited to 
CLOSE. If the programmer closes the 
file, he may do so in either the 
declarative section or in the main 
body of his program. 



DIRECT or RELATIVE (SEQUENTIAL) 

• Operating System: If no error 
processing option is specified, a 
message is written to the console 
providing identification of the file 
and type of input/output error. 
Then control is returned to the 
system. For sequential data sets, 
if EROPT has SKP or ACC (as 
specified in the JCL for the data 
set), an ABEND will not occur and 
processing will continue. 

• INVALID KEY: A transfer of control 
to the procedure indicated in the 
INVALID KEY phrase occurs if 
additional space cannot be allocated 
to write the record requested. This 
condition occurs when either no more 
space is available or 16 extents 
have already been allocated on the 
last volume assigned to the data 
set. The transfer of control occurs 
only if a secondary-quantity is 
specified in the DD statement SPACE, 
SPLIT, or SUBALLOC parameter. If no 
secondary- quantity is specified, the 
primary-quantity is assumed to be 
the exact amount of space required 
for the data set and any attempt to 
write a record beyond the storage 
allocated causes the program to end 
abnormally. When an INVALID KEY 
error occurs, the file can be closed 
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so that it may subsequently be 
reopened for retrieval as INPUT or 
1-0. 

• USE AFTER STANDARD ERROR: The 
programmer may specify this option 
in order to display the cause of the 
error. Control goes to the 
declarative section. The programmer 
can check the error type in the 
section by specifying data-name- 1 in 
the GIVING option. If the error is 
not the result of an invalid key, 
processing of the file is limited to 
CLOSE. If the programmer elects to 
close the file, he may do so in 
either the declarative section or in 
the main body of his program. 

Note s : The user should consider the 
following when a relatively large number of 
INVALID KEY exits or declarative sequences 
(with GO TO exits) are to be executed: 



There are two different kinds of labels, 
standard and nonstandard. Magnetic tape 
volumes can have standard or nonstandard 
laoels, or they can be unlabeled. The 
type(s) of label processing for tape 
volumes to be supported by an installation 
is selected during the system generation 
process. Mass storage volumes are 
supported with standard labels only. 



Standard labels consist of volume labels 
and groups of data set labels. The volume 
label group precedes or follows data on the 
volume; it identifies and describes the 
volume. The data set label groups precede 
and follow each data set on the volume, and 
identify and describe the data set. 



• The data set labels that precede the 
data set are called header labels. 



1. The distinction between error 
processing via an error declarative 
and the INVALID KEY clause. When an 
input/output operation is requested, a 
storage area (called an input/output 
block, or IOB) is allocated until the 
request is satisfied (or, in the event 
of an error, until return from the 
user-provided error-handling routine) . 
If the error declarative is used, a 
normal exit from the declarative 
returns control to the system and 
frees the IOB. When the INVALID KEY 
routine is used, however, the system 
does not regain control, and the IOB 
is not freed. 

2. The error declarative dynamically 
allocates storage for a register save 
area upon entry. If a GO TO statement 
is used to exit from the declarative, 
neither this save area nor the IOB is 
freed. 



The data set labels that follow the 
data set are called trailer labels. 
They are almost identical to the header 
labels. 



• The data set label groups can 
optionally include standard user labels 
except for ISAM files. 

• The volume label groups can optionally 
include standard user labels for QSAM 
files. 



Nonstandard labels can have any format 
and are processed by routines provided by 
the programmer. Unlabeled volumes contain 
only data sets and tapemarks. In the job 
control statements, a DD statement must be 
provided for each data set to be processed. 
The LABEL parameter of the DD statement is 
used to describe the data set' s labels. 



To make the maximum space available to 
other users, the programmer should 
rely on the declarative as much as 
possible, taking a normal exit from 
it. Otherwise, it is recommended that 
the programmer specify a larger 
region. 



Specific information about the contents 
and physical location of labels is 
contained in the publications IBM OS Data 
Manage ment Services , Order No. GC 26-3746, 
and IBM OS Tape Labels , Order 
No. GC28-6680. 



VOLUME LABELING 



STANDARD LABEL FORMAT 



Various groups of labels may be used in 
secondary storage to identify magnetic-tape 
and mass storage volumes, as well as the 
data sets they contain. The labels are 
used to locate the data sets and are 
identified and verified by label processing 
routines of the operating system. 



Standard labels are 80-character records 
that are recorded in EBCDIC and odd parity 
on 9-track tape; or in BCD and even parity 
on 7-track tape. The first four characters 
are always used to identify the labels. 
These identifiers are: 
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V0L1 

HDR1 and HDR2 — 

EOV1 and EOV2 — 

EOF1 and EOF2 -- 

UHL1 to UHL8 
UTL1 to UTL8 



volume label 
data set header 
labels 

data set trailer 
labels (end-of -volume) 
data set trailer labels 
(end-of-data set) 
user header labels 
user trailer labels 



The format of the mass storage volume 
label group is the same as the format of 
the tape volume label group, except one of 
the data set labels of the initial volume 
label consists of the data set control 
block (DSCB). The DSCB appears in the 
volume table of contents (VTOC) and 
contains the equivalent of the tape data 
set header and trailer information, in 
addition to space allocation and other 
control information. 



STANDARD LABEL PROCESSING 



Standard label processing as performed 
by the system consists of the following 
basic functions: 

• Checking the labels on input data sets 
to ensure that the correct volume is 
mounted, and to identify, describe, and 
protect the data set being processed. 

• Checking the existing labels on output 
data sets to ensure that the correct 
volume is mounted and to prevent 
overwriting of vital data. 

• Creating and writing new labels on 
output data sets. 



When a data set is opened for input, the 
volume label and the header labels are 
processed. For an input end-of-data 
condition, the trailer labels are processed 
when a CLOSE statement is executed. For an 
input end-of-volume condition, the trailer 
labels on the current volume are processed, 
and then the volume label and header labels 
on the next volume are processed. 

When a data set is opened for output, 
the existing volume label and HDRl label 
are checked, and new header labels are 
written. For an output end-of-volume 
condition, trailer labels are written on 
the current volume, the existing volume 
labels and header labels on the next volume 
are checked, and then new header labels are 
written on the next volume. When an output 
data set is closed, trailer labels are 
written. 



STANDARD USER LABELS 



Standard user labels contain 
user-specified information about the 
associated data set. User labels are 
optional within the standard label groups. 
The format used for user header labels 
(UHL1-8) and user trailer labels (UTL1-8) 
consists of a label 80 characters in length 
recorded in EBCDIC on 9-track tape units, 
or in BCD on 7-track tape units. The first 
three bytes consist of the characters that 
identify the label: UHL for a user header 
label (at the beginning of a data set) or 
UTL for a user trailer label (at the 
end-of-volume or end-of-data set). The 
next byte contains the relative position of 
this label within a set of labels of the 
same type and can be any number from 1 
through 8. The remaining 76 bytes consist 
of user-specified information. 

User labels are generally created, 
examined, or updated when the beginning or 
end of a data set or volume (reel) is 
reached. User labels are applicable for 
sequential, direct, and relative data sets. 
For sequentially processed data sets, end 
or beginning of volume exits are allowed 
(i.e., "intermediate" trailers and headers 
may be created or examined). For direct or 
relative data sets # user label routines 
will be given control only during OPEN or 
CLOSE condition for a file opened as INPUT, 
OUTPUT, or I-O. Trailer labels for files 
opened as INPUT or 1-0 are processed when a 
CLOSE statement is executed for the file 
that has reached an AT END condition. 
Thus, for standard sequential data sets, 
the user may create, examine, or update up 
to eight header labels and eight trailer 
labels on each volume of the data set, 
whereas for direct or relative data sets 
the user may create, examine, or update up 
to eight header labels during OPEN and up 
to eight trailer labels during CLOSE. Note 
that these labels reside on the initial 
volume of a multi-volume data set. This 
volume must be mounted at CLOSE if trailer 
labels are to be created, examined, or 
updated. 

When standard user label processing is 
desired, the user must specify the label 
type of the standard and user labels (SUL) 
on the DD statement that describes the 
dataset. For mass storage volumes, 
specification of a LABEL subparameter of 
SUL results in a separate track being 
allocated for use as a user-label track 
when the data set is created. This 
additional track is allocated at initial 
allocation and for sequential data sets at 
end-of-volume (volume switch) time. The 
user- label track (one per volume of a 
sequential data set) will contain both user 
header and user trailer labels. 
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User Lab e l To taling 
(BSAM and QSAM only) 



When creating or processing a data set 
with user labels on a sequential file, the 
programmer may develop control totals to 
obtain exact information about each volume 
of the data set. This information can be 
stored in his user labels. For example, a 
control total accumulated as the data set 
is created, can be stored in a user label 
and later compared with a total accumulated 
while processing a volume. The user 
totaling facility enables the programmer to 
synchronize the control data that he has 
created while processing a data set with 
records physically written on a volume. In 
this way, he can tell exactly what records 
were written. This information can also be 
used for accurately labeling tape reels 
(i.e., assigning physical adhesive labels). 



To request this option, specify OPTCD=T 
in the DC3 parameter of the DD statement. 
The user's TOTALING area, where control 
data is accumulated, is provided by the 
user. In this area, the user can store 
information on each record he writes. When 
an input/output operation is scheduled, the 
control program sets up a user TOTALED save 
area that preserves an image of the 
information in the user's TOTALING area. 
When the output USE LABEL declarative is 
entered, the values accumulated in the 
user's TOTALING area corresponding to the 
last record actually written on the volume 
are stored in the TOTALED area. These 
values can be included in user labels. 

When using this facility for an output 
data set (i.e., when creating the data 
set), the programmer must update his 
control data in the TOTALING area prior to 
issuing a WRITE instruction. When 
subsequently using this data set for input, 
the programmer can accumulate the same 
information as each record is read. These 
values can be compared with the ones 
previously stored in the user label when 
the records were created. 

Variable length records with APPLY 
WRITE-ONLY Or records with SAME RECORD AREA 
specified require special considerations 
when using the TOTALING option. Since the 
control program determines whether a 
variable-length record will fit in a buffer 
after a WRITE instruction has been issued, 
the values accumulated may include one more 
record than is actually written on the 
volume. In this case, the programmer must 
update his TOTALING area after issuing a 
WRITE instruction. 



For further information on user label 
totaling, see the Program Product 
publication I BM O S Full American N ational 
Standard COBOL. 



NONSTANDARD LABEL FORMAT 



Nonstandard labels do not conform to the 
standard label formats. They are designed 
by programmers and are written and 
processed by programmers. Nonstandard 
labels can be any length less than 4096 
bytes. There are no requirements as to the 
length, format, contents, and number of 
nonstandard labels, except that the first 
record on the volume cannot be a standard 
volume label. In other words, the first 
record cannot be 80 characters in length 
with the identifier VOLl as its first four 
characters. 



NONSTANDARD LABEL PROCESSING 



To use nonstandard labels (NSL), the 
programmer must: 

• Create nonstandard label processing 
routines for input header labels, input 
trailer labels, output header labels, 
and output trailer labels. 

• Insert these routines into the 
operating system as part of the SVC 
library (SYS1. SVCLIB) . 

• Code NSL in the LABEL parameter of the 
DD statement at execution time. 

The system verifies that the tape has a 
nonstandard label. Then if NSL is 
specified in the LABEL parameter, it loads 
the appropriate NSL routines into transient 
areas. These NSL routines are entered at 
OPEN, CLOSE, and END- OF- VOLUME conditions 
by the respective executors. 

For a data set opened as output, the NSL 
routines entered include: 

• At OPEN time, a header routine to check 
the old header and/or create the new 
header; 

• At CLOSE time, a trailer-creation 
routine; 

• At EOV time, a trailer-creation routine 
and a header routine. 



User label totaling is not available 
with S-mode records. 



For a data set opened as input essentially 
the same types of routines are required. 
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Note: The NSL routines must observe the 
following conventions: 

1. Follow Type-IV SVC routine 
conventions. 

2. Use GETMAIN and FREEMAIN for work 
areas. 

3. Be reentrant load modules of 1024 
bytes each. 

4. Use EXCP for I/O operations and XCTL 
for passing control among load modules 
and then returning to the I/0-support 
routines. 

5. Begin with the letters NSL if the 
system branches to them directly. 
(Other user-written modules having to 
do with nonstandard labels must begin 
with the letters IGC. ) 

6. Have as their entry points the first 
byte in each load module. 

In addition, the NSL routines must write 
their own tapemarks, do all I/O operations 
necessary (via EXCP) , determine when all 
labels have been processed, and take care 
of data set positioning. These routines 
may communicate at the LABEL source level 
with USE BEFORE LABEL PROCEDURE 
declaratives by means of linkage described 
under "User Label Procedure." 



USER LABEL PROCEDURE 



The USE. . . LABEL PROCEDURE statement 
provides the user with label handling 
procedures at the COBOL source level to 
handle nonstandard or user labels. The 
BEFORE option indicates processing of 
nonstandard labels. The AFTER option 
indicates processing of standard user 
labels. The labels must be listed as 
data-names in the LABEL RECORDS clause in 
the File Description entry for the file. 
When the file is opened as input, the label 
is read in and control is passed to the USE 
declarative if a USE... LABEL PROCEDURE is 
specified for the OPEN option or for the 
file. If the file is opened as output, a 



ffor = r- 



:fe 



area tor 



fnv ^V,i 



label is provided and 



control is passed to the USE declarative if 
a USE... LABEL PROCEDURE is specified for 
the OPEN option or for the file. For files 
opened as INPUT or I-O, control is passed 
to the USE declarative to process trailer 
labels when a CLOSE statement is executed 
for the file that has reached the AT END 
condition. A more detailed discussion of 
the USE. ..LABEL PROCEDURE statement is 
contained in the Program Product 
publication IBM OS Full American National 
Standard COBOL. 



One of the concerns of the programmer is 
linkage between the nonstandard label SVC 
routine and the USE BEFORE LABEL PROCEDURE 
section. Other problems related to writing 
nonstandard label SVC routines are 
discussed in the publication IBM OS System 
Programmer 1 s Guide . 

When the nonstandard label SVC routine 
has determined that a particular DCB has 
nonstandard labels, the nonstandard label 
routine must inspect the DCB exit list for 
an active entry to ensure that there is a 
USE BEFORE. . .LABEL section for this DCB and 
for that type of label processing. The DCB 
field EXLST contains a pointer to this exit 
list. An active entry is defined as a 
1-byte code other than X' 00' or X' 80' 
followed by a 3-byte address of the 
appropriate label section (Figure 35). 



r t- 

| Code | 



Exit List 



(USE section for header labels) 
(USE section for trailer labels) 



Notes : 

1. Code 1 is set to X'01' indicating 
INPUT, or X'02* indicating OUTPUT. 

2. Code 2 is set to ' X'OD' indicating 
INPUT, or X'04' indicating OUTPUT. 

L 

Figure 35. Exit List Codes 



Once the nonstandard label SVC routine 
tests that the exit list confirms an 
appropriate active entry, it must pass the 
address of a parameter list in register 1. 

The parameter list (Figure 36) must have 
the following format. 



r t n 

| 1 byte | 3 bytes | 
r + 4 4 

| Byte | | Adabel buffer) | 
! Byte 4 ! Flag byte \ A (DCB) \ 

I Byte 8 | Error flag | j 

l j. ± J 

Figure 36. Parameter List Formats 



The Adabel buffer) is the address of 
the label record on input and the address 
where the label will be created on output. 

The A(DCB) is the address of the DCB. 
The DCB contains a pointer to the DEB. The 
nonstandard label SVC routine must test the 
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EOF bit in the OFLGS field of the DEB (data 
extend block) to determine whether to 
return control to the EOV or CLOSE module. 

Control is given to the CLOSE module only 
at EOF. 

The error flag byte will have bit set 
to 1 if an input/output error occurs when 
reading or writing a label. 



The user's nonstandard label routines 
are responsible for all tape positioning. 
For multifile volumes, the user may specify 
a file sequence number in the LABEL 
parameter on the DD card. The nonstandard 
label routines can inspect this information 
in the JFCB and position the files 
accordingly. For additional information, 
see the IBM OS System Pr ogrammer 1 s Guide. 
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| Routine Type | Return Code (Applicable Note | 
y + + .j 



Input header | 

and/or | 

trailer j 
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1 
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Output header | 
and/or j 
trailer | 


4 
8 


T 
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1 

2 


T 

Update header] 
and/or j 
trailer j 


8 
12 
16 


T 


1 
2 
3 



|. x x j, 

Notes: 

1. For output mode, the label is 
written or rewritten. For input 
mode, normal processing is resumed; 
any additional user labels are 
ignored. 

2. Another label is read (for input 
mode) and control is returned to the 
USE BEFORE LABEL PROCEDURE section. 
For output mode, the labels should 
be written and control should be 
returned to the USE BEFORE LABEL 
PROCEDURE section. When control is 
returned to the nondeclarative 
portion, either normal processing 
will continue or the label section 
will be re-entered, depending on 
whether the return code is 4 or 8. 

3. A return code of 16 indicates that 
the USE BEFORE LABEL PROCEDURE 
section has determined that an 
incorrect volume was mounted. When 
LABEL- RETURN is set to a nonzero 
value, the return code is set to 16. 

l 

Figure 37. Label Routine Return Codes 



ASCII File Labels 



ASCII files on magnetic tape may have 
American National Standard labels or 
American National Standard and user labels, 
or they may have no label. Any labels on 
an ASCII tape must be in ASCII code. Tapes 
containing a combination of ASCII and 
EBCDIC labels are not read. All the record 
formats supported ( i. e. , fixed, undefined, 
and variable) are allowed on ASCII files, 
regardless of whether or not the files are 
labeled. Spanned records are not supported 
under ASCII. 

When American National Standard labels 
are being processed, the label type must be 
specified in the DD statement that 
describes the data set. The parameter for 
American National Standard labels is 
LABEL=AL. The parameter for American 
National Standard and user labels is 
LABEL=AUL. Nonstandard labels are not 
permitted for ASCII files. The user may 
indicate no labels as LABELS=NL. 



ASCII Standard Label Processing 



Standard label processing for ASCII 
files is identical to standard label 
processing for files coded in EBCDIC. 
ASCII code is translated into EBCDIC code 
prior to processing. 



When the USE BEFORE LABEL PROCEDURE 
section returns control to the nonstandard 
label SVC routine, it will pass a return 
code that will indicate whether or not more 
labels are to be processed (Figure 37). 
This return code is set by assigning a 
value to the special register LABEL-RETURN. 



The maximum size of the label record is 
stored on a halfword boundary at the 
EXITLIST address +38. 



ASCII User Label _ Processing 



All American National Standard user 
labels (LABEL=AUL) are optional. ASCII 
files may have user header labels (UHLn) 
and user trailer labels (UTLn), which are 
processed very much like the standard user 
labels on EBCDIC files. However, there is 
no limit to the number of user labels 
possible at the beginning and the end of a 
file. No check is made on the number of 
labels written. It is left to the user to 
determine how many labels he wants written. 
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All user labels must be 80 bytes in User Label E xits 
length, but they may contain any user 
information desired. 

To create or verify user labels, the 
programmer must code for the file a USE 
Note : USE BEFORE STANDARD LABEL procedures AFTER STANDARD LABEL procedure, 
are not allowed, because they are 
nonstandard. 
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RECORD FORMATS 



Logical records may be in one of four 
formats: fixed-length (format F), 
variable-length (format V), unspecified 
(format U), or spanned (format S). F-mode 
files must contain records of equal 
lengths. Files containing records of 
unequal lengths must be V-mode, U-mode, or 
S-mode. Files containing logical records 
that are longer than physical records must 
be S-mode. 



The record format is specified in the 
RECORDING MODE clause in the Data Division. 
If this clause is omitted, the compiler 
determines the record format from the 
record descriptions associated with the 
file. If the file is to be blocked, the 
BLOCK CONTAINS clause must be specified in 
the Data Division. 



The prime consideration in the selection 
of a record format is the nature of the 
file itself. The programmer knows the type 
cf input his program will receive and the 
type of output it will produce. The 
selection of a record format is based on 
this knowledge as well as an understanding 
of the type of input/output devices on 
which the file is written and of the access 
method used to read or write the file. 



The number of logical records within a 
block (blocking factor) is normally 
constant for every block in the file. When 
fixed-length records are blocked, the 
programmer specifies the BLOCK CONTAINS 
clause in the file description (FD) entry 
in the Data Division. 



In unblocked format F, the logical 
record constitutes the block. The BLOCK 
CONTAINS clause is unnecessary for 
unblocked records. 

Format F records are shown in Figure 38. 
The optional control character, represented 
by the letter C in Figure 37 is used for 
stacker selection and carriage control. 
When carriage control or stacker selection 
is desired, the WRITE statement with the 
ADVANCING or POSITIONING option is used to 
write records on the output file. In this 
case, one character position must be 
included as the first character of the 
record. This position will be 
automatically filled in with the carriage 
control or stacker select character. The 
carriage control character never appears 
when the file is written on the printer or 
punched on the card punch. 



Not e: Illustrations of unblocked Format F 
records do not take into account the key 
field required when direct organization is 
used. 



FIXED- LENGTH (FORMAT F) RECORDS 



Format F records are fixed-length 
records. The programmer specifies format F 
records by including RECORDING MODE IS F in 
the file description entry in the Data 
Division. If this clause is omitted and 
both of the following are true: 

• All records in the file are the same 
size 

• BLOCK CONTAINS [integer-1 TO] 
integer-2... does not specify 
integer- 2 less than the length of the 
maximum level-01 record 

the compiler determines the recording mode 
to be F. All records in the file are the 
same size if there is only one record 
description associated with the file and it 
contains no OCCURS clause with the 
DEPENDING ON option; or if multiple record 
descriptions are all the same length. 
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Figure 38. Fixed-length (Format F) Records 
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UNSPECIFIED (FORMAT U> RECORDS 



VARIA3LE LENGTH (FORMAT V) RECORDS 



Format U is provided to permit the 
processing of any blocks that do not 
conform to F, V, or S formats. Format U 
records are shown in Figure 39. The 
optional control character C, as discussed 
under "Fixed-Length (Format F) Records, " 
may be used in each logical record. 



The programmer specifies format U 
records by including RECORDING MODE IS U in 
the file description (FD) entry in the Data 
Division. U-mode records may be specified 
only for direct or standard sequential 
files. 

If the RECORDING MODE clause is omitted, 
and BLOCK CONTAINS [integer-1 TO] 
integer-2... does not specify integer-2 
less than the maximum level- 01 record, the 
compiler determines the recording -mode to 
be U if the file is direct and one of the 
following conditions exist: 



The programmer specifies format V 
records by including RECORDING MODE IS V in 
the file description entry in the Data 
Division. V-mode records may be specified 
only for direct or standard sequential 
files. If the RECORDING MODE clause is 
omitted and BLOCK CONTAINS t integer-1 TO] 
integer-2... does not specify integer-2 
less than the maximum level-01 record, the 
compiler determines the recording mode to 
be format V if the file is standard 
sequential and one of the following 
conditions exist: 



• The FD entry contains two or more 
level-01 descriptions of different 
lengths. 



• A record description contains an OCCURS 
clause with the DEPENDING ON option. 



• The FD entry contains two or more 
level-01 descriptions of different 
lengths. 

• A record description contains an OCCURS 
clause with the DEPENDING ON option. 

• A RECORD CONTAINS clause specifies a 
range of record lengths. 



The RECORD CONTAINS clause specifies a 
range of record lengths. 



V-mode records, unlike U-mode or F-mode 
records, are preceded by fields containing 
control information. These control fields 
are illustrated in Figures 40 and 41. 



Each block on the external storage media 
is treated as a logical record. There are 
no record-length or block-length fields. 

When a READ INTO statement is used for a 
U-mode file, the size of the longest record 
for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. 



The first four bytes of each block 
contain control information (CO : 



LL — represents two bytes designating 

the lenqth of the block (including 
the 'CC« field). 



BB — represents two bytes reserved for 
system use. 



Note: Illustrations of Format U records do 
not take into account the key field 
required when direct organization is used. 



The first four bytes of each logical 
record contain control information (cc) : 
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Figure 39. Unspecified (Format U) Records 



11 — represents two bytes designating 

f Vip lQf;ii-al r-oi-Ttrr\ lesnnr-l-h 

(including the 'cc* field). 

bb — represents two bytes reserved for 
system use. 

For unblocked V-mode records (Figure 
40), the Data portion + CC + cc constitute 
the block. 

For blocked V-mode records (Figure 41), 
the Data portion of each record + the cc of 
each record + CC constitute the block. 
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Figure 40. Unblocked V-Mode Records 



FD VARIABLE-FILE-1 

RECORDING MODE IS V 

BLOCK CONTAINS 35 TO 80 CHARACTERS 
RECORD CONTAINS 27 TO 72 CHARACIERS 
DATA RECORD IS VARIABLE- RECORD- 1 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE- RECORD- 1. 
LOGICAL RECORD 
05 FIELD-A PIC X(20). 
05 FIELD-B PIC 99. 
05 FIELD-C OCCURS 1 TO 10 TIMES 

DEPENDING ON 

FIELD-B PIC 9(5). 



Variable-length record descriptions, for 
input and output files, must not define 
space for the control bytes. Control bytes 
are automatically provided when a record is 
written and are not communicated to the 
user when a file is read. Although they do 
not appear in the descriptions of logical 
records, control bytes do appear in the 
buffer areas of main storage. The compiler 
automatically allocates input and output 
buffers that are large enough to contain 
the required control bytes. 



When variable-length records are written 
on unit record devices, control bytes are 
neither printed nor punched. They do 
appear, however, on other external storage 
devices. V-mode records moved from an 
input buffer to a working storage area will 
be moved without the control bytes. 



The LABEL RECORDS clause is always 
required. The DATA RECORD (S) clause is 
never required. If the RECORDING MODE 
clause is omitted, the compiler determines 
the mode as V since the record associated 
with VARIABLE-FILE-1 varies in length 
depending on the contents of FIELD-B. The 
RECORD CONTAINS clause is never required. 
The compiler determines record sizes from 
the record description entries. The BLOCK 
CONTAINS clause is also not required, since 
the compiler assumes unblocked records if 
the clause is omitted. Note: Record 
length calculations are affected by the 
following: 



When the BLOCK CONTAINS clause with the 
RECORDS option is used, the compiler 
adds four bytes to the logical record 
length and four more bytes to the block 
length. 



Note : When a READ INTO statement is used 
for a V-mode file, the size of the longest 
record for that file is used in the MOVE 
statement. All other rules of the MOVE 
statement apply. 



Consider the following standard 
sequential file consisting of unblocked 
V-mode records : 



When the BLOCK CONTAINS clause with the 
CHARACTERS option is used, the user 
must include each cc + CC in the length 
calculation. In the definition of 
VARIABLE-FILE-1, the BLOCK CONTAINS 
clause specifies eight more bytes than 
does the RECORD CONTAINS clause. Four 
of these bytes are the logical record 
control bytes and the other four are 
the block control bytes. 



1st 
Logical Record 



2nd 
Logical Record 



3rd 
Logical Record 
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Figure 41. Blocked V-Mode Records 



146 



In Example 1, assume that FIELD-B 
contains the value 02 for the first record 
of a file and FIELD-B contains the value 03 
for the second record of the file. The 
first two records will appear on an 
external storage device and in buffer areas 
of main storage as shown in Figure 42. 

If the file described in Example 1 had a 
blocking factor of 2, the first two records 
would appear on an external storage medium 
as shown in Figure 43. 

Example 2 : 

If VARIABLE- FILE -2 is blocked, with 
space allocated for three records of 
maximum size per block, the following FD 
entry could oe used when the file is 
created: 



As mentioned previously, the RECORDING 
MODE, RECORD CONTAINS, and DATA RECORDS 
clauses are unnecessary. By specifying 
that each block contains three records, the 
programmer allows the compiler to provide 
space for three records of maximum size 
plus additional space for the required 
control bytes. Hence, 316 character 
positions are reserved by the compiler for 
each output buffer. If this size is other 
than that required, the BLOCK CONTAINS 
clause with the CHARACTERS option should be 
specified. If the block size is to be 
specified at execution time by use of the 
3LKSIZE subparameter on an associated DD 
card, BLOCK CONTAINS CHARACTERS must be 
specified. 



FD VARIABLE- FILE- 2 

RECORDING MODE IS V 

BLOCK CONTAINS 3 RECORDS 

RECORD CONTAINS 20 TO 100 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD- 1 , 

VARIABLE- RECORD- 2 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE-RECORD-1. 

05 FIELD-A PIC X(20>. 
05 FIELD-B PIC X(80). 

01 VARIABLE-RECORD- 2. 

05 FIELD-X PIC X(20). 



Note: Blocked variable-length records are 
permitted only when the file processing 
technique is standard sequential. 



In Example 2, assume that the first six 
records written are five 100-character 
records followed by one 20-character 
record. The first two blocks of 
VARAIBLE-FILE-2 will appear on the external 
storage device as shown in Figure 44. 



1st Block 



2nd Block 



r T — T T — T T — T T T T — T T — T T — T T T n 

| 0040 | BB | 036 | bb | FIELD-A | 02 | FIELD-C | FIELD-C | 0045 | BB | 0041 | bb | FIELD-A | 03 | FIELD-C | FIELD-C | FIELD-C | 
L J- -L -L -L J- J- X X J. X X X JL X X X J 

Note : Lengths appear in decimal notation for illustrative purposes. 



Figure 42. Fields in Unblocked V-Mode Records 




r T T T T T T T T T T T T T T 1 

| 0081 | BB| 0036 | bb| FIELD-A| 02 | FIELD-C | FIELD-C | 0041 | bb| FIELD-A| 03 | FIELD-C | FIELD-C | FIELD-C | 
L X X X X X X X X X X X X X X J 



Note: Lengths appear in decimal notation for illustrative purposes. 

L J 

Figure 43. Fields in Blocked V-Mode Records 
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1st Block 



2nd Block 



r T T T T T T T T T T f g p g pa T T T T T T 1 

j 316 j BB j 104 j bb j Data j 104 f bb j Data j 104 | bb| Data feS 236 | BB 1 104 | bbj Data 1 104 | bb | Data | 24 | bb | Data | 
i x — x x — x x x — x x x x smm&A. x x x x x x j 

Note : Lengths appear in decimal notation for illustrative purposes. 



'"Figure W. "First "Two" Blocks' of VARIABLE-FILE- 2 



The buffer for the second block is 
truncated after the sixth WRITE statement 
is executed since there is not enough space 
left for a maximum size record. Hence, 
even if the seventh WRITE to 
VARIABLE- FILE- 2 is a 20-character record, 
it will appear as the first record in the 
third block. This condition can be 
eliminated by using the APPLY WRITE-ONLY 
clause when creating files of 
variable-length blocked records. 

Note : Illustrations of unblocked Format V 
records do not take into account the key 
field required when direct organization is 
used. 



r T T T T T T T T T T 1 

j 236 I bb I 24 j bb j Data 1 104 j bb | Data j 104 j bb j Data | 

L X X X X X X X X X X J 



Using the APPLY WRITE-ONLY clause causes 
a buffer to be truncated only when the next 
record does not fit in the buffer. That 
is, if the next three WRITE statements to 
the file specify VARIABLE- RECORD- 2, the 
block is created containing six logical 
records, as shown below: 



| 308 | bb | 24 | bb | Data j 104 | bb | Data 1 104 | bb | Data : 

l X X X X X X X X X X , 



APPLY WRITE-ONLY Clause 



1 



T T T T T T T T 1 

24 | bb | Data j 24 j bb j Data | 24 1 bb j Data j 

X X X X X X X X J 



The APPLY WRITE-ONLY clause is used to 
make optimum use of buffer space when 
creating a standard sequential file with 
blocked V-mode records. 



Note: When using the APPLY WRITE-ONLY 
clause, records must not be constructed in 
buffer areas. An intermediate work area 
must be used with a WRITE FROM statement. 



Suppose VARIABLE- FILE- 2 is being created 
with the following file description entry: 



SPANNED (FORMAT S) RECORDS 



FD VARIABLE- FILE- 2 

RECORDING MODE IS V 

BLOCK CONTAINS 316 CHARACTERS 

DATA RECORDS ARE VARIABLE-RECORD- 1, 

VARIABLE- RECORD- 2 
LABEL RECORDS ARE STANDARD. 

01 VARIABLE- RECORD- 1. 

05 FIELD-A PIC X(20). 
05 FIELD-B PIC X(80). 

01 VARIABLE- RECORD- 2. 

05 FIELD-X PIC X(20). 



The first three WRITE statements to the 
file create one 20-character record 
followed by two 100-character records. 
Without the APPLY WRITE-ONLY clause, the 
buffer is truncated after the third WRITE 
statement is executed since the maximum 
size record no longer fits. The block is 
written as shown below: 



A spanned record is a logical record 
that may be contained in one or more 
physical blocks. Format S records may be 
specified for direct (BDAM, BSAM) files and 
for standard sequential (QSAM) files 
assigned to magnetic tape or to mass 
storage devices. 

When creating files with S-mode records! 
if a record is larger than the remaining 
space in a block, a segment of the record 
is written to fill the block. The 
remainder of the record is stored in the 
next block or blocks, as required. 

When retrieving a file with S-mode 
records, only complete records are made 
available to the user. 

Spanned records are preceded by fields 
containing control information. Figure 44 
illustrates the control fields. 
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BDF (Block Descriptor Field) : 

LL — represents two bytes designating 
the length of the physical block 
(including the block descriptor 
field itself). 



described in the Data Division with the 
following file description entry: 

FD SFILE 

RECORD CONTAINS 250 CHARACTERS 
BLOCK CONTAINS 100 CHARACTERS 



BB — represents two bytes reserved for 
system use. 



SDF (Segment Descriptor Field) : 



11 






vpnrpcQp-l-c 4- Xjgr\ V\\r+* oc r^ooi rrr»^4-TJ r> rr 

the length of the record segment 
(including the segment descriptor 
field itself). 



bb — represents two bytes reserved for 
system use. 

N ote ; There is only one block descriptor 
field at the beginning of each physical 
block. There is # however, one segment 
descriptor field for each record segment 
within the block. 



Figure 46 also illustrates the concept 
of record segments. Note that the third 
block contains the last 50 b w tes of REC— 1 
and the first 50 bytes of REC-2. Such 
portions of logical records are called 
record segments. It is therefore correct 
to say that the third block contains the 
last segment of REC-1 and the first segment 
of REC-2. The first block contains the 
first segment of REC-1 and the second block 
contains an intermediate segment of REC-1. 



S-MODE CAPABILITIES 



Each segment of a record in a block, 
even if it is the entire record, is 
preceded by a segment descriptor field. 
The segment descriptor field also indicates 
whether the segment is the first, the last, 
or an intermediate segment. Each block 
includes a block descriptor field. These 
fields are not described in the Data 
Division; provision is automatically made 
for them. These fields are not available 
to the user. 

A spanned blocked file may be described 
as a file composed of physical blocks of 
fixed length established by the programmer. 
The logical records may be either fixed or 
variable in length and that size may be 
smaller, equal to, or larger than the 
physical block size. There are no required 
relationships between logical records and 
physical block sizes. Records of a spanned 
file may only be blocked when organization 
is sequential (QSAM). 

A spanned unblocked file may be 
described as a file composed of physical 
blocks each containing one logical record 
or one segment of a logical record. The 
j.ogxca.1. records may j^e Giunci lIXcu or 
variable in length. When the physical 
block contains one logical record, the 
lenqth of the block is determined by the 
logical record size. When a logical record 
has to be segmented, the system always 
writes the largest physical block possible. 
The system segments the logical record when 
the entire logical record cannot fit on the 
track. 

Figure 46 is an illustration of blocked 
spanned records of SFILE. SFILE is 



Formatting a file in the S-mode allows 
the user to make the most efficient use of 
external storage while organizing data 
files with logical record lengths most 
suited to his needs. 

1. Physical record lengths can be 
designated in such a manner as to make 
the most efficient use of track 
capacities on mass storage devices. 

2. The user is not required to adjust 
logical record lengths to maximum 
physical record lengths and their 
device-dependent variants when 
designing his data files. 

3. The user has greater flexibility in 
transferring logical records across 
DASD types. 

Spanned record processing will support 
the 2400 tape series, the 2311 and 2314 
disk storage devices, and the 2321 data 
cell drive. 



SEQUENTIAL S-MODE FILES (QSAM) FOR TAPE OR 
MASS STORAGE DEVICES 



When the spanned format is used for QSAM 
files, the logical records may be either 
fixed or variable in length and are 
completely independent of physical record 
length. A logical record may span physical 
records. A physical record may contain one 
or more logical records and/or segments of 
logical records. 
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Figure 45. Control Fields of an S-Mode Record 



■100 bytes- 

REC-1 
1st Block 



< 

r 

I 

L 



I G | 
J L. 



-100 bytes- 

REC-1 
2nd Block 



-> <-50 bytes-> <-50 bytes-> 
■i r r — t 1 



I G 

J L. 



REC-1 | REC-2 
X 

3rd Block 



x J 



L 



. J 



Figure 46. One Logical Record Spanning Physical Blocks 



S our c e Language c on siderations 



The user specifies S-mode by describing 
the file with the following clauses in the 
file description (FD) entry of his COBOL 
program: 

• BLOCK CONTAINS integer- 2 CHARACTERS 

• RECORD CONTAINS [ integer- 1 TO] 
integer-2 CHARACTERS 

• RECORDING MODE IS S 



Integer-2 is less than the maximum 
length of a variable level-01 FD entry 
(i.e., an entry containing one or more 
OCCURS clauses with the DEPENDING ON 
option) . 



Except for the APPLY WRITE-ONLY, APPLY 
RECORD- OVERFLOW, WRITE BEFORE ADVANCING, 
WRITE AFTER ADVANCING, or WRITE AFTER 
POSITIONING clauses, all the options for a 
variable file apply to a spanned file. 



The size of the physical record must be 
specified using the BLOCK CONTAINS clause 
with the CHARACTERS option. Any block size 
may be specified. Block size is 
independent of logical record size. 

The size of the logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
will determine the maximum record size from 
the record descriptions under the FD. 

Format S may be specified by the 
RECORDING MODE IS S clause. If this clause 
is omitted, the compiler will set the 
recording mode to S if the BLOCK CONTAINS 
inteter-2 CHARACTERS clause was specified 
and either of the following conditions 
exist: 

• Integer-2 is less than the largest 
fixed-length level-01 FD entry. 



Pro ce ssing Seg u ential S-Mode Files (QS AM ) 



Suppose a file has the following file 
description entry: 

FD SPAN-FILE 

BLOCK CONTAINS 100 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS DATAREC. 



01 DATAREC. 

05 FIELD-A PIC X (100). 
05 FIELD-B PIC X (50). 



Figure 47 illustrates the first four 
blocks of SPAN-FILE as they would appear on 
external storage devices (i.e., tape or 
mass storage) or in buffer areas of main 
storage. 
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Note s ; 

1. The RECORDING MODE clause is not 
specified. The compiler determines 
the recording mode to be S since the 
block size is less than the record 
size. 

2. The length of each physical block is 
100 bytes, as specified in the BLOCK 
CONTAINS clause. All required control 
fields, as well as data, must be 
contained within these 100 bytes. 

3. No provision is made for the control 
fields within the level-01 entry 
DATAREC. 

The preceding discussion dealt with 
S-mode records which were larger than the 



physical blocks that contained them. It is 
also possible to have S-mode records which 
are equal to or smaller than the physical 
blocks that contain them. In such cases, 
the RECORDING MODE clause must specify S 
(if so desired) since the compiler cannot 
determine this by comparing block size and 
record size. 

One advangage of S-mode records over 
V-mode records is illustrated by a file 
with the following characteristics: 

1. RECORD CONTAINS 50 TO 150 CHARACTERS 

2. BLOCK CONTAINS 350 CHARACTERS 

3. The first five records written are 
150, 150, 150, 100, and 150 characters 
in length. 
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Figure 47. First Four Blocks of SPAN-FILE 



RECORDING MODE IS V 



RECORDING MODE IS S 



| 150 | 150 | G | 150 | 100 1 G | 150 | 

L J. J L X J L J 



Rl 



R2 



R3 



R4 



R5 



j 150 j 150 j 50 1 G | 100 | 100 | 150 | 

L X X J L X X J 



Rl 



R2 



R3 



R4 



R5 



Note ; The enclosed diagrams are for illustrative purposes only. Neither takes into 
account the space required for control fields. 



Figure 48. Advantage of S-Mode Records Over V-Mode Records 
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For V-mode records, buffers are 
truncated if the next logical record is too 
large to be completely contained in the 
block (Figure 48). This results in more 
physical blocks and more inter-record gaps 
on the external storage device. 

Note : For V-mode records, buffer 
truncation occurs: 

1. When the maximum level-01 record is 
too large. 

2. If APPLY WRITE-ONLY or SAME RECORD 
AREA is specified and the actual 
logical record is too large to fit 
into the remainder of the buffer. 



the Logical Record Area is not used. 
Regardless, only complete logical records 
are made available to the user. Both READ 
and WRITE statements should be thought of 
as manipulating complete logical records 
not record segments. 



The allocation of a Logical Record Area 

-Hia- 5 *-— b@— -3— di-s-w-dva&tasre -feG—fefe©— GOBQL— ss-s-sr*- - 

Additional main storage, consisting of 36 
bytes + the maximum record length, will 
always be required. The Logical Record 
Area is discussed in detail in "Finding 
Data Records in an Abnormal Termination 
Dump. " 



For S-mode records, all blocks are 350 
bytes in length and records that are too 
large to fit entirely into a block will be 
segmented. This results in more efficient 
use of external storage devices since the 
number of inter-record gaps are minimized 
(Figure 48). 

A second advangage of S-mode processing 
over that of V-mode is that the user is no 
longer limited to a record length that does 
not exceed the track of the mass storage 
device selected. Records may span tracks, 
cylinders, extents, and volumes. 

QSAM spanned records differ from other 
QSAM record formats because of an 
allocation of an area of main storage known 
as the "Logical Record Area. " If logical 
records span physical blocks, COBOL will 
use this Logical Record Area to assemble 
complete logical records. If logical 
records do not span blocks (i.e., they are 
contained within a single physical block) 



DIRECTLY ORGANIZED S-MODE FILES (BDAM AND 
BSAM) 



When S-mode is used for directly 
organized files, only unblocked records are 
permitted. Logical records may be either 
fixed or variable in length. A logical 
record will span physical records if, and 
only if, it spans tracks. A physical 
record will contain only one logical record 
or a segment of a logical record. A track 
may contain a segment of a logical record, 
or segments of two logical records and/or 
whole logical records. Records may span 
tracks, cylinders, and extents, but not 
volumes. 
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Figure 4 9. Direct and Sequential Spanned Files on a Mass Storage Device 
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Source Language - Considerations 



The user specifies S-mode by describing 
the file with the following clauses in the 
file description (FD) entry of his COBOL 
program: 



• BLOCK CONTAINS integer- 2 CHARACTERS 



RECORD CONTAINS tinteger-1 TO] 
integer- 2 CHARACTERS 



In the sequential file, each physical 
block is 3625 bytes in length and is 
completely filled with logical records. 
The file consists of three physical blocks, 
occupies three tracks, and contains no 
inter-record gaps. 

In the direct file, the physical blocks 
vary in length. Each block contains only 
one logical record or one record segment. 
Logical record R3 spans physical blocks 
only because it spans tracks. The file 
consists of seven physical blocks, occupies 
more than three tracks, and contains three 
inter-record gaps. 



• RECORDING MODE IS S 

The size of a logical record may be 
specified by the RECORD CONTAINS clause. 
If this clause is omitted, the compiler 
will determine the maximum record size from 
the record descriptions under the FD. 

The spanned format may be specified by 
the RECORDING MODE IS S clause. If this 
clause is omitted, the compiler will set 
the recording mode to S if the BLOCK 
CONTAINS integer-2 CHARACTERS clause was 
specified and integer-2 is less than the 
greatest logical record size. This is the 
only use of the BLOCK CONTAINS clause. It 
is otherwise treated as comments. 

The physical block size is determined by 
either: 

1. The logical record length. 

2. The track capacity of the device being 
used. 



If, for example, the track capacity of a 
mass storage device is 3625 characters, any 
record smaller than 3625 characters may be 
written as a single physical block. If a 
logical record is greater than 3625 
characters, the record is segmented. The 
first segment may be contained in a 
physical block of up to 3625 bytes, and the 
remaining segments must be contained in 
succeeding blocks. In other words, a 
logical record will span physical blocks 
if, and only if, it spans tracks. 

Figure 49 illustrates four 
variable-length records (Rl, R2, R3, and 
R4) as they would appear in direct and 
sequential files on a mass storage device. 
In both cases, control fields have been 
omitted for illustrative purposes. For 
both files, assume: 

1. BLOCK CONTAINS 3625 CHARACTERS (track 
capacity = 3625 > 

2. RECORD CONTAINS 500 TO 5000 CHARACTERS 



Processing Di rectly Org ani zed S- M ode Files 
(BDAM and BSAM) 



When processing directly organized 
files, there are two advantages spanned 
format has over the other record formats : 

1. Logical record lengths may exceed the 
length restriction of the track 
capacity of the mass storage device. 
If, for example, the track capacity of 
a mass storage device is 2000 bytes, 
this does not represent the maximum 
length of the logical record that can 
be specified (even when the device 
does not have a Track Overflow 
feature) . 

Note : Even when the spanned format is 
used, the COBOL restriction on the 
length of logical records must be 
adhered to (i.e., a maximum length of 
32,767 characters). 

2. S-mode records give the user the same 
facility as the Track Overflow 
feature. If neither RECORDING MODE IS 
S nor APPLY RECORD-OVERFLOW is 
specified, only complete logical 
records can be written on any single 
track. This means that when a track 
has only 900 unoccupied bytes and a 
record of 1000 bytes is to be added, 
it will be written on the next 
available track. This is inefficient, 
since a 900 byte segment could be 
added to the current track by means of 
either APPLY RECORD-OVERFLOW or 
RECORDING MODE IS S. 

Note : If a choice exists between 
Track Overflow and S-mode records, 
neither has any particular advantage 
over the other with regard to the 
efficient use of storage space. 

The disadvantage of BSAM and BDAM 
spanned records is similar to that 
mentioned for QSAM. A segment work area is 
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always allocated which occupies additional 
main storage. 

Like QSAM, the processing of BSAM and 
BDAM spanned records relies on an 
interaction between buffers, segment work 
areas, and Logical Record Areas. For QSAM, 
input-output buffers are used as the 
segment work area and complete logical 

.records are assembled., in. .a_.Lo_ai.caX ..Re.cor.d. 

Area before being made available to the 
user if the record is segmented. If the 
record is not segmented, the logical record 
is made available to the user within the 
buffer unless the SAME AREA clause is 
specified. For BSAM and BDAM, input-output 
buffers are used as a Logical Record Area 
and a separate segment work area must be 
allocated. Segment work areas and Logical 
Record Areas are described fully in 
"Finding Data Records in an Abnormal 
Termination Dump. " 



2. When the object of the DEPENDING ON 
option is changed as a result of a 
move to it or to a group that contains 
it. (The length is not calculated 
when a move is done to an item which 
redefines or renames it. ) 



Consider the f-Qiiowi-Jig e-xampi 



WORKING-STORAGE SECTION. 

77 C0NTR0L-1 PIC 99. 

77 WORKAREA-1 PIC 9<6>V99. 



01 SALARY-HISTORY. 

05 SALARY OCCURS TO 10 TIMES 
DEPENDING 
ON CONTROL- 1 PIC 9(6)V99. 



OCCURS CLAUSE WITH THE DEPENDING ON OPTION 



If a record description contains an 
OCCURS CLAUSE WITH THE DEPENDING ON option, 
the record length is variable. This is 
true for records described in an FD as well 
as in the Working-Storage section. The 
previous sections discussed four different 
record formats. Three of them, V-mode, 
U-mode, and S-mode, may contain one or more 
OCCURS clauses with the DEPENDING ON 
option. 

The following section discusses some 
factors that affect the manipulation of 
records containing OCCURS clauses with the 
DEPENDING ON option. The text indicates 
whether the factors apply to the File (FD) 
or Working-Storage sections, or both. 

The compiler calculates the length of 
records containing an OCCURS clause with 
the DEPENDING ON option at two different 
times, as follows (the first applies to FD 
entries only, the second to both FD and 
Working-Storage entries) : 



When a file is read and the object of 
a DEPENDING ON option is within the 
record. 



The Procedure Division statement MOVE 5 
TO CONTROL-1 will cause a recalculation of 
the length Of SALARY-HISTORY. MOVE SALARY 
(5) TO WORKAREA-1 will not cause the length 
to be recalculated. 

The compiler permits the occurrence of 
more than one level- 01 record, containing 
the OCCURS clause with the DEPENDING ON 
option, in the same FD entry (Figure 50). 
If the BLOCK CONTAINS clause is omitted, 
the buffer size is calculated from the 
longest level-01 record description entry. 
In Figure 50, the buffer size is determined 
by the description of RECORD-1 (RECORD-1 
need not be the first record description 
under the FD) . 

During the execution of a READ 
statement, the length of each level-01 
record description entry in the FD will be 
calculated (Figure 50). The length of the 
variable portions of each record will be 
the product of the numeric value contained 
in the object of the DEPENDING ON option 
and the length of the subject of the OCCURS 
clause. In Figure 50, the length of 
FIELD-1 is calculated by multiplying the 
contents of CONTROL-1 by the length of 
FIELD-1; the length of FIELD- 2, by the 
product of the contents of CONTROL- 2 and 
the length of FIELD-2; the length of 
FIELD-3 by the contents of CONTROL-3 and 
the length of FIELD-3. 
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FD INPUT-FILE 



DATA. RECORDS ARE RECORD-1 RECORD- 2 RECORD-3. 

01 RECORD-1. 

02 CONTROL-1 PIC 99. 

02 FIELD-1 OCCURS TO 10 TIMES DEPENDING ON CONTROL-1 PIC 9(5). 

01 RECORD- 2. 

02 CONTROL- 2 PIC 99. 

02 FIELD- 2 OCCURS 1 TO 5 TIMES DEPENDING ON CONTROL-2 PIC 9(4). 

01 RECORD-3. 

02 FILLER PIC XX. 

02 CONTROL- 3 PIC 99. 

02 FIELD-3 OCCURS TO 10 TIMES DEPENDING ON CONTROL-3 PIC X(4). 

Figure 50. Calculating Record Lengths When Using the OCCURS Clause with the DEPENDING ON 
Option 



Since the execution of a READ statement 
makes available only one record type (i.e., 
RECORD-1 type, RECORD-2 type, or RECORD-3 
type), two of the three record descriptions 
in Figure 50 will be inappropriate. In 
such cases, if the contents of the object 
of the DEPENDING ON option does not conform 
to its picture, the length of the 
corresponding record will not be 
calculated. For the contents of an item to 
conform to its picture: 



An item described as USAGE DISPLAY must 
contain decimal data. 



An item described as USAGE 
COMPUTATIONAL- 3 must contain internal 
decimal data. 



The following example illustrates the 
length calculations made by the system when 
a READ statement is executed: 



FD 



01 



01 



RECORD-1. 
05 A PIC 99. 
05 B PIC 99. 

05 C PIC 99 OCCURS 5 TIMES 
DEPENDING ON A. 



RECORD 


-2. 




05 D 


PIC 


XX. 


05 E 


PIC 


99. 


05 F 


PIC 


99. 


05 G 


PIC 


99 



OCCURS 5 TIMES 



DEPENDING ON F. 



An item described as USAGE 
COMPUTATIONAL must contain binary data. 



WORKING-STORAGE SECTION. 



01 TABLE- 3. 

05 H OCCURS 10 TIMES DEPENDING ON B. 



01 TABLE- 4. 

05 I OCCURS 10 TIMES DEPENDING ON E. 
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When a record is read, lengths are 
determined as follows: 

1. The length of RECORD-1 is calculated 
using the contents of field A. 

2. The length of RECORD-2 is calculated 
using the contents of field F. 

3. The length of TABLE.- 3. is calculated 

using the contents of field B. 

H. The length of TABLE-4 is calculated 
using the contents of field E. 



The user should be aware of several 
additional factors that affect the 
successful manipulation of variable-length 
records. The following example illustrates 
a group item (i.e., REC-1) whose 
subordinate items contain an OCCURS clause 
with the DEPENDING ON option and the object 
of that DEPENDING ON option. 

WORKING- STORAGE SECTION. 
01 REC-1. 

05 FIELD-1 PIC S9. 

05 FIELD-2 OCCURS 5 TIMES DEPENDING ON 
FIELD-1 PIC X(5). 



01 



REC-2. 

05 REC-2-DATA 



PIC X(50) 



other words, if FIELD-1 does not 
contain an external decimal item, the 
length of REC-1 will not be 
recalculated. 

Note: According to the COBOL description, 
FIELD-2 can occur a maximum of five timers 
If, however, FIELD-1 contains an external 
decimal item whose value exceeds five, the 
length of REC-1 will still be c-aicuicrted. 
One possible consequence of this invalid 
calculation will be encountered if the user 
attempts to initialize REC-1 by moving 
zeros or spaces to it. This initialization 
would inadvertently delete part of the 
adjacent data stored in REC-2. 

The following example applies to 
updating a record containing an OCCURS 
clause with the DEPENDING ON option and at 
least one other subsequent entry. In this 
case, the subsequent entry is another 
OCCURS clause with the DEPENDING ON option. 

WORKING- STORAGE SECTION. 
01 VARIABLE-REC. 

05 FIELD-A PIC X(10). 

05 CONTROL-1 PIC S99. 

05 CONTROL-2 PIC S99. 

05 VARY-FIELD-1 OCCURS 10 TIMES 

DEPENDING ON CONTROL-1 PIC X(5)„ 
05 VARY-FIELD-2 OCCURS 10 TIMES 

DEPENDING ON CONTROL-2 PIC X(9). 



The results of executing a MOVE to the 
group item REC-1 will be affected by the 
following: 

• The length of REC-1 may have been 
calculated at some time prior to the 
execution of this MOVE statement. The 
user should be sure that the current 
length of REC-1 is the desired one. 

• The length of REC-1 may never have been 
calculated at all. In this case, the 
result of the move will be 
unpredictable. 

• After the move, since the contents of 
FIELD-1 have been changed, an attempt 
will be made to recalculate the length 
of REC-1. This recalculation, however, 
will be made only if the new contents 
of FIELD-1 conform to its picture. In 



01 STORE- VARY-FIELD- 2. 

05 VARY-FLD-2 OCCURS 10 TIMES 

DEPENDING ON CONTROL-2 PIC X(9). 



Assume that CONTROL-1 contains the value 
5 and VARY-FIELD-1 contains 5 entries. 

In order to add a sixth field to 
VARY-FIELD-1, the following steps are 
required: 

MOVE VARY-FIELD-2 TO STORE- VARY-FIELD- 2. 
ADD 1 TO CONTROL-1. 
MOVE ' additional field' TO 
VARY-FIELD-1 (CONTROL-1). 
MOVE STORE- VARY-FIELD- 2 TO VARY-FIELD-2. 

For a discussion of the use of the 
OCCURS DEPENDING ON clause in a sort 
program, see "Sorting Variable-Length 
Records. " 
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SYMBOLIC DEBUGGING FEATURES 



A. programmer using the Full American 
National Standard COBOL Compiler, Version 
4, under the IBM Operating System, has 
several methods available to him for 
testing and debugging his programs. Use of 
the symbolic debugging features is the 
easiest and most efficient method for 
testing and debugging and is described in 
detail in this chapter. 

"Appendix A: A Sample Program" contains 
an example of a program run without the 
symbolic debugging features. The chapter 
"Program Checkout" contains information 
useful for finding the instruction that 
causes the abnormal termination and then 
correcting the problem. The chapters 
"Output" and "Using the Checkpoint/Restart 
Feature" include a discussion of compiler 
output and a description of taking 
checkpoints and restarting programs, 
respectively. 



USE OF THE SYMBOLIC DEBUGGING FEATURES 



output generated for each of these 
features. 



STATE Option 



If the STATE option is in effect and an 
abnormal termination occurs, the printed 
output includes the compiler-generated card 
number or, if NUM is in effect, the card 
sequence number for the last verb executed. 
To use the STATE option, the programmer 
must: 

• Request the option at compile time by 
specifying STATE in the PARK field or, 
if a cataloged procedure is used, in 
the PARM. COB field. 

• Include a //SYSDBOUT DD card for the 
output data set at execution time. 

For additional information, see "Options 
for the Compiler. " 



As an aid to debugging, compiler options 
can be requested that provide additional 
diagnostic information for an abnormal 
termination other than "Canceled by 
Operator" or, under MVT, as a result of 
exceeding the system-state time slice. 
Three user options are available for 
object-time debugging — the statement 
number option (STATE), the flow trace 
option (FLOW), and the symbolic debug 
option (SYMDMP). 

The STATE option causes the number of 
the card for the last verb executed before 
termination to be printed out. The FLOW 
option causes a trace of the last 
user-specified number of procedures 
executed to be printed out (with a default 
of 99). Both STATE and FLOW cause the 
PROGRAM-ID, the condition code, and the 
last problem PSW to be printed out. The 
SYMDMP option enables the user to request a 
symbolic formatted dump of the data area of 
the object program for an abnormal 
termination, or to request dynamic dumps of 
data areas at strategic points during 
execution. 



FLOW Option 



If the FLOW option is in effect, a 
formatted list containing the PROGRAM-ID 
and either the compiler-generated card 
number or the line number (if NUM is in 
effect) of the last n executed procedures 
is printed on SYSDBOUT. The number of 
procedures traced can vary from 1 to 99 and 
is specified by the programmer. To use the 
flow trace facility, the programmer must: 

• Request a trace at compile time by 
specifying FLOW in the PARM field or, 
if a cataloged procedure is used, in 
the PARM. COB field. 

• Indicate the number of procedures to be 
traced at compile time or, by 
specifying FLOW[=nn] on the EXEC card, 
at execution time. 

• Include a //SYSDBOUT DD card for the 
output data set to be used for the 
trace. 



Use of these features requires no source 
lanquage coding; rather the user specifies 
these options at compile time, through job 
control language. Operation of the SYMDMP 
option is dependent on execution-time 
control cards. Figure 51 illustrates the 



The number of procedures to be traced may 
be specified at compile time via either the 
PARM parameter or, if a cataloged procedure 
is used, the PARM. COB field. This number 
may be overridden at execution time via the 
PARM parameter or, if a cataloged procedure 
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is used, the PARM.GO parameter. If the 
number of procedures traced is specified at 
neither compile time nor execution time, 
either the default value of 99 or the value 
specified at program product installation 
will be employed. 
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be specified at compile time and remain in 
effect for every program in the batch. To 
suppress a trace For a particular program 
within the batch, the programmer should 
specify NOFLOW at execution time as the 
last parameter in the PARM field for that 
program, or change the CBL card. For more 
information, see the sections "Options for 
the compiler" and "Options for Execution. " 

Note : The FLOW option is completely 
independent of the READY/RESET TRACE 
feature of the debugging language. 



(c) For an RD — the card number, the 
report-name, the type, the report 
line, and the contents of 

PAGE- COUNTER and LINE -COUNTER if 
present. 

(d) For a CD — the CD itself in its 
implicit format, as well as the 

, area containing the message data 
currently being __bujif pred* 

(e) For an index name — the name, the 
type, and the contents in decimal. 

The symbolic dump option is reguested at 
compile time via the SYMDMP option, through 
the PARM parameter of the EXEC card. 
Operation of the symbolic dump option is 
dependent on object-time control cards 
placed in the SYSDBG data set. This data 
set must consist of unblocked 80-byte 
records. If the object-time control cards 
are not present, SYMDMP is cancelled at 
execution time. These cards are discussed 
below. 



If the SYMDMP option is in effect, a 
symbolic formatted dump of the object 
program' s data area is produced when the 
program abnormally terminates. This option 
also enables the programmer to reguest 
dynamic dumps of specified data-names at 
strategic points during program execution. 
If two or more COBOL programs are 
link-edited together and one of them 
terminates abnormally, a formatted dump is 
produced for all programs in the calling 
seguence compiled with the SYMDMP option, 
up to and including the main program. 

Note: The terminating program need not 
have been compiled with the SYMDMP option. 

The abnormal termination dump consists 
of the following parts : 

1. An abnormal termination message, 
including the number of the statement 
and of the verb being executed at the 
time of an abnormal termination. 

2. Selected areas in the Task Global 
Table. 

3. h formatted dump of the Data Division 
including: 

(a) For an SD — the card number, the 
sort-file-name, the type, and the 
sort record. 

(b) For an FD -- the card number, the 
file-name, the type, the ddname, 
the DECB and/or DCB status, the 
contents of the DEC3 and/or DCB in 
hexadecimal, and the fields of the 
record. 



Object-Time Control Cards 



The operation of the SYMDMP option is 
determined by two types of control cards : 

Program- control card — required if 
abnormal termination and/or dynamic 
dumps are requested. 

Line-control card — required only if 
dynamic dumps are requested. 

S yntax Rules : The fields of both the 
program-control card and the line-control 
card must conform to the following rules : 

1. Control cards are essentially free 
form, i.e., parameters coded on these 
cards can start in any column. 
However, parameters may not extend 
beyond column 71. 

2. Each parameter except the last must be 
immediately followed by a comma or a 
blank. 

3. No commas are needed to account for 
optional parameters that are not 
specified. 

4. All upper-case letters in IBM 
documentation represent specifications 
that are to appear in the actual 
statement exactly as saown, 

5. All lower-case letters represent 
generic terms that are to be replaced 
in the actual statement. 



158 



6. Brackets are used to indicate that a 
specification is optional and is not 
always required in the statement. 

7. Brackets enclosing stacked items 
indicate that a choice of one item 
may, but need not, be made by the 
programmer . 

8. Braces enclosing stacked items 
indicate that a choice of one item 
must be made by the programmer. 

9- All punctuation marks and special 
characters shown in the statement 
formats other than hyphens, brackets, 
braces, and underscores, must be 
punched exactly as shown. This 
includes commas, parentheses, and the 
equal sign. 

Note: Blanks may be substituted for 
commas. 



Cont inuation Cards ; To continue either the 
program-control card or the line-control 
card, the programmer must code a nonblank 
character in column 72 of the continued 
card. Individual keywords and data-names 
cannot be split between cards. 



Cont r ol S tate ment Placement : If a main 
program is compiled with the SYMDMP option, 
or if at least one subprogram called by the 
main program is a COBOL program compiled 
with the SYMDMP option, the control cards 
may either follow or precede the 
programmer's data, if any, in the input 
stream: 



//GO EXEC 
//GO. SYSDBG DD 



PGM= 
* 



{user's control cards! 



/* 

//GO. SY3IN 



DD 



{user's data cards, if any} 



/* 



For an example of the control statements 
used to compile a program with the SYMDMP 
option, see Figure 51. 

Program- Control Cards : A program-control 
card must be present at execution time for 
any program requesting a SYMDMP service. 
Program- control cards have the following 
format: 



program-id, ddname [, ENTRY] 
where: 



(HEX) ( 
(NOHEX) ,' 



program- id 

is a 1-8 character program-name of a 
COBOL program compiled with the SYMDMP 
option. This parameter is required 
and must appear first on the 
program-control card. 

ddname 

is the ddname assigned to the file 
that was produced at compile time on 
SYSUT5. This parameter is required 
and must follow the program-id. 

ENTRY 

NOENTRY 

ENTRY is used to provide a trace of a 
program-name when several programs are 
link-edited together. Each time the 
program whose PROGRAM- ID matches the 
"program- id" parameter is entered, its 
name is displayed. 



HEX 
NOHEX 



is optional and refers to the format 
of the Data Division area in the 
abnormal termination dump. If HEX is 
specified, level-01 items are provided 
in hexadecimal. Items subordinate to 
level-01 items are printed in EBCDIC, 
if possible. Level-77 items are 
provided both in EBCDIC and 
hexadecimal. If HEX is not specified, 
items subordinate to level-01 items 
and level-77 items are provided in 
EBCDIC. If these items are 
unprintable, hexadecimal notation is 
provided. 



Line-Control Cards : Line-control cards 
have the following format: 

line-num[, (verb-num) ] [,ON n] [, m] [,k] 



, (HEX) 
, (NOHEX) 

", (HEX) " 
, NOHE X) 



,ALL 



{,namel [THRU name2]}, 



line-num 

indicates the card number associated 
with the point in the Procedure 
Division at which the dynamic dump is 
to be taken. The card number is 
either the compiler-generated number 
or, if NUM is in effect, the user's 
number in card columns 1 through 6. 

verb-num 

indicates the position of the verb in 
the card indicated by "line-num" 
before whose execution a dynamic dump 
is taken. When "verb-num" is not 
specified, the value 1 is assumed; 
when specified, "verb-num" must follow 
"line-num" and may not exceed 15. 
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ON n[,m] [,k] 

is equivalent to the COBOL statement 
ON n AND EVERY m UNTIL k. . . This 
option limits the requested dynamic 
dumps to specified times. For 
example, "ON n" would result in one 
dump, qiven the nth time "line-num" is 
reached during execution. "ON n,m" 
would result in a dump the first time 
at the. nth execution _ of ..".linfi.-n.um-"- and 
thereafter at every mth execution 
until end-of-job. 



been compiled with the SYMDMP option and no 
symbolic dump is required at execution 
time, the input data set is not required. 
In this case, SYMDMP responds with the 
following message: 

IKF177I- SYMDMP CANCELLED. NO CONTROL 
CARDS. 



SAMPLE PROGRAM — TESTRUN 



HEX 

NOHE X 

refers to the format of the Data 
Division areas provided in the dynamic 
dump. If HEX is specified, level-01 
items are provided in hexadecimal. 
Items subordinate to level-01 items 
are printed in EBCDIC, if possible. 
Level-77 items are printed in both 
EBCDIC and hexadecimal. If HEX is not 
specified, items subordinate to 
level-01 items and level-77 items are 
provided in EBCDIC. If the items are 
unprintable, hexadecimal notation is 
provided. Note that if "namel" is 
specified and it represents a group 
item and HEX has not been specified, 
neither the group nor the elementary 
items in the group will be provided in 
hexadecimal. 

namel [THRU name2] 

represents selected areas of the Data 
Division to be dumped. With the THRU 
option, a range of data-names 
appearing consecutively in the Data 
Division is dumped. "namel" and 
"name2" may be qualified but not 
subscripted. If the programmer wishes 
to see a subscripted item, specifying 
the name of the item without the 
subscript results in a dump of every 
occurrence of that item. 



ALL 



results in a dump of everything that 
would be dumped in the event of an 
abnormal termination. The purpose of 
ALL is to allow the programmer to 
receive a formatted dump at normal 
end-of-job. To do this, the generated 
statement number of the line on which 
a STOP RUN, EXIT PROGRAM, or GOBACK 
statement appears must oe specified as 
the "line-num" parameter. 



OVERALL CONSIDERATIONS 



The end-of-file control card, slash 
asterisk (/*) must end the symbolic debug 
control card data set. If a run unit 
includes one or more programs that have 



Figure 51 is an illustration of a 
program that utilizes the Symbolic 
Debugging feature. In the following 
description of the program and its output, 
letters identifying the text correspond to 
letters in the program listing. 

Ch\ Because the SYMDMP option is requested 
^""^ in the PARM parameter of the EXEC 

card, the logical unit SYSUT5 must be 

assigned at compile time. 

\Bj The PARM parameter specifications on 
the EXEC card indicate that an 
alphabetically ordered cross-reference 
dictionary, a flow trace of 10 
procedures, and the SYMDMP option are 
being requested. 

[CJ An alphabetically ordered 

cross-reference dictionary of 
data-names and procedure-names is 
produced by the compiler as a result 
of the SXREF specification in the PARM 
parameter of the EXEC card. 

(d) The file assigned at compile time to 
SYSUT5 to store SYMDMP information is 
assigned to DD1 at execution time. 

Ql\ The SYMDMP control cards placed in the 
input stream at execution time are 
printed along with any diagnostics. 







The first card is the 
program-control card where: 

(a) TESTRUN is the PROGRAM-ID. 

(b) DDl is the ddname of the 
SYSUT5 file at execution time. 

\2J The second card is a line-contrcl 
card which requests a (HEX) 
formatted dynamic dump of KOUNT, 
NAfcE-FIELD, NO-OF-DEPENDENTS, and 
RECORD-NO prior to the first and 
every fourth execution of 
generated card number 70. 

(3) The third card is also a 

line-control card which requests a 
(HEX) formatted dynamic dump of 
WORK-RECORD and B prior to the 
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execution of generated card number 
81. 

The type code combinations used to 
identify data-names in abnormal 
termination and dynamic dumps are 
defined. Individual codes are 
illustrated in Table 20. 

The dynamic dumps requested by the 
first line-control card. 

The dynamic dumps requested by the 
second line-control card. 

Program interrupt information is 
provided by the system when a program 
terminates abnormally. 

The statement number information 
indicates the number of the verb and 
of the statement being executed at the 
time of the abnormal termination. The 
name of the program containing the 
statement is also provided. 

A flow trace of the last 10 procedures 
executed is provided because FLOW=10 
was specified in the PARM parameter of 
the EXEC card. 

Selected areas of the Task Global 
Table are provided as part of the 
abnormal termination dump. 



M] For each file-name, the generated card 
number, the file type, the file 
status, the file organization, the DCB 
status, and the fields of the DCB and 
DECB, if applicable, are provided in 
hexadecimal. 

Hi) The fields of records associated with 
each FD are provided in the format 
requested on the program-control card. 



The contents of the fields of the 
Working-Storage Section are provided 
in the format requested on the 
program-control card. 

The value associated with each of the 
possible subscripts is provided for 
each of the data items described with 
an OCCURS clause. 

Asterisks appearing within the EBCDIC 
representation of the value of a given 
field indicate that the type and the 
actual content of the field conflict. 



© 



© 



© 
© 



01 RECORDA. 

05 FIELD-A. 

10 FIELD-A1 PIC X. 
10 FIELD-A2 PIC X. 

will appear as follows in SYMDMP output: 

01 RECORDA. . . 

02 FIELD-A. . . 

03 FIELD-A1... 
03 FIELD-A2... 



Debugging TESTRUN 



1. Reference to the statement number 
information J provided by the SYMDMP 
option shows that the abnormal 
termination occurred during the 
execution of the first verb on card 
81. 

2. Generated card number 81 contains the 
statement COMPUTE B = B + 1. 

3. Through verification of the contents 
of B at the time of the abnormal 
termination R, it can be seen that 
the usage of B (numeric packed) 
conflicts with the value contained in 
the data area reserved for B (numeric 
display) . 

4. The abnormal termination occurred 
during an attempt to perform an 
addition on a display item. 

More complex errors may require the use 
of dynamic dumps to isolate the problem 
area. Line-control cards are included in 
TESTRUN merely to illustrate how they are 
used and what output they produce. 



Table 20. 



Code 



Individual Type Codes Used in 
SYMDMP Output 

•T 

| Meaning 



Note : When the SYMDMP option is used, 
level numbers appear "normalized" in the 
symbolic dump produced. For example, a 
group of data items described as: 





A 


Alphabetic 






B 


Binary 






D 


Display 






E 


Edited 






* 


Subscripted Item 






F 


Floating Point 






N 


Numeric 






P 


Packed Decimal 






S 


Signed 






OL 


Overpunch Sign Leading 






OT 


Overpunch Sign Trailing 






SL 


Separate Sign Leading 






ST 


Separate Sign Trailing 










_j 
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IEF298I DEBUG SYSOUT=U. 

//DEBUG JOB 7074722674, ' D. DAVIDSON' , MSGLEVEL=1. MSGCLASS=G 
//JOBLIB DD DSN=DUMMY0S,UNIT=2314,VOL=SER=DC156,DISP=SKR 
// DD DStJ=PRODVER4, DISP=SHR 

■// EXLC UCOB4CLG, PARM. COB='DMAP, PyAP.oXREF, FLOW=10, SYMDKP, QUOTE, NORES' 
XXCOB EXEC PGM=IKFCBL0C, REGIGN=80K, PARM=(LOAD) 00000010 

//COB. SYSPRINT DD SYSOUT=G, OUTLIM=1000 SKF 

X/SYSPRINT DD SYSOUT=U, OUTLIM=1000 00000SK.F 

XXSYSUDUN'P DD SYSOUT=U, OUTLIM=1000 OOOOOSfcF 

XXSYSUT1 DD SPACE=(CYL, (10, 2)), UNIT=2314 00000040 

XXSYSUT2 DD SPACE= (CYL, (10, 2 ) ) , UNIT= (2314 , SEP=SY3UT1) 00000050 

XXSYSUT3 DD SPACE= (CYL. ( 10. 2) ) . UNIT=< 2314. SEP= ( SYSUT1 . SVStlT? ) 1 00000060 

XXSYSUT4 DD SPACE= (CYL, (10, 2 ) > , UNIT= (2314, SEP= (SYSUT1, SYSUT2, SYSUT3) ) 00000070 
•-//COB. SYSUT5 DD DSNAME=66UT5 r UNIT=SYSDA, SPACE=(TRK, ( 100, 10) ) , 

// DISP=( NEW, PASS) 

X/SYSQTb ■ uls •■■SPaC'E-*U"SX;'(2Cr,2/T,"UiaT=23liT";'DSTJ='£"SYl?IDBG, DISP= (NEW, PASS") 00'00 0'CP"0 
XXSYSLIN DD DSN=6LOADSET, DISP=(MOD ( PASS) , UNIT=2314, SPACZ=(CYL, (10, 2 ) ) 00000090 

//COB. SYSIN DD * 

Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 1 of 11) 
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IEC130I SYSLIB DD STATEMENT MISSING 

IKF373I STEP /COB / START 72144.0024 

IEF374I STEP /COB / STOP 72144.0029 CPU OMIN 04. 09SEC MAIN 78K LCS OK 

STEP COB ENDED. COMP CODE 0004 CORE REQUSTED= 0080K. CORE USED= 0078K. «U= 2, 02 

XXLKED EXEC PGM=IEWL, PARM=(XREF, LIST, LET), COND=(5,LT, COB), 00000100 

XX REGION=96K 00000110 

XXSYSLIN DD DSN=SLOADSET, DISP= (OLD, DELETE) 00000120 

XX DD DDNAME=SYSIN 00000130 

XXSYSLMOD DD DSN=6GODATA(RUN) , DISP= (NEW, PASS) , 00000140 

XX UNIT=2314,SPACE=(1024, (50, 20, 1)) 00000150 

//LKED. SYSLIB DD DSN=NEWSYMJB, UNIT=2314, VOL=SER=DC157, DISP=SHR 

X/SYSLIB DD DSN=SYS1.DYNAKLIB, DISP=SHR 00000160 

// DD DSNAME=SYS1. DYNAMLI3, DISP=SHP 

X/ DD DSN=SYS1.TELCMLIB, DISP=SHR 00000170 

XXSYSUT1 DD UNIT=(2314,SEP=(SYSLIN,SYSLMOD> ) , SPACE= (1024, (50, 20) ) 000001S0 

//LKED.S23PRINT DD SYSOUT=G, OUTLIM=1000 SMF 

X/SYSPRINT DD SYSOUT=U, OUTLIM=lC00 000003MF 

XXSY3UDUMP DD SYSOUT=U, OUTLIM=1000 000OOSMF 



IEF373I STEP /LKED / START 72144.0029 

IEF374I STEP /LKED / STOP 72144.0030 CPU 0MIN 00.67SEC MAIN 96K LCS OK 

STEP LKED ENDED. COMP CODE 0000 CORE REQUSTED= 0096K. CORE USED= 0096K. HU= . oO 

XXGO EXEC PGM=*.LKED.SYSLMOD,COND=( (5.LT.COB), (5,LT, LKED) ) 00000210 

//GO. SYSUDUMP DD SYSOUT=G, OUTLIM=1000 SMF 

X/SYSUDUMP DD SYSOUT=U,OUTLIM=1000 00000SKF 

XXSYSDBOUT DD SYSOUT=U, OUTLIM=1000 00000SMF 

//GO. DD1 DD DSN=6£UTS,UNIT=SYSDA, DISP=<OLD, DELETE) 

X/DD1 DD DSN=6SYMDBG,DISP= (OLD, DELETE) 00000240 

//GO. SAMPLE DD UNIT=2400, LABEL=( , NL) , DISP=( NEW, DELETE) , VOL=SER=TESTER 

//GO.SYSOUT DD SYSOUT=G,OUTLIM=1000 SMF 

//GO. SYSDBOUT DD SYSOUT=G, OUTLIM=1000 SI-'F 

//GO.STEPLIB DD DSN=NEWSYMJB, UNIT=2314, VOL=SER=DC157, DISP=SHR 

// DD DSNAME=SYS1.DYNAMLIB,DISP=SHR 

//GO.SYSDBG DD * 

// 



Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 2 of 11) 
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IEC130I SYSDTERM DD STATEMENT MISSING 
A 0001 NYC 

1 

2 

3 

4 



1 

2 



0002 NYC 

0003 NYC 

0004 NYC 

0005 tJYC 

0006 NYC 

0007 NYC 

0008 NYC 

0009 NYC 



IEF460I WTP MESSAGE LIMIT EXCEEDED 
COMPLETION CODE - SYSTEM=0C7 DSER=0000 
IEF242I ALLOC. FOR DEBUG GO 



AT AEEND 



IEF237I 136 ALLOCATED TO JOBLIB 

ALLOCATED Tu 

ALLOCATED TO PGM=*.DD 

ALLOCATED TO SYSUDUMP 

ALLOCATED__TO_ SYSDBOUT 

ALLOCATED TO DDl 

ALLOCATED TO SAMPLE 

ALLOCATED TO SYSOUT 

ALLOCATED TO SYSDBOUT 

ALLOCATED TO STEPLIB 

ALLOCATED TO 

ALLOCATED TO SYSDBG 
DUMMY0S PASSED 

VOL SER NOS= DC156 . 

PRODVER4 PASSED 

VOL SER NOS= DC160 . 

SYS72144. T002347. RV000. DEBUG. GODATA PASSED 

VOL SER NOS= 231400. 

SYS72144. T002347.SVOO0. DEBUG. R0000011 SYSOUT 
VOL SER NOS= 231402. 

SYS72144.T002347.SV000. DEBUG. R0000012 SYSOUT 
VOL SER NOS= 231402. 

SYS72144.T002347.RV000.DE3UG. UT5 DELETED 

VOL SER NOS= 231401. 

SYS72144. T002347. RV000. DEBUG. R0000013 DELETED 
VOL SER NOS= TESTER. 

SYS72144.T002347. SV000. DEBUG. R0000014 DELETED 
VOL SER NOS= 231402. 

SYS72144. T002347. SV000. DEBUG. R0000015 DELETED 
VOL SER NOS= 231402. 

NEWSYMJB KEPT 

VOL SER NOS= DC157 . 

SYS1.DYNAMLIB KEPT 

VOL SER NOS= DC160 . 

SYS72144.T002347.RV000. DEBUG. S0000016 SYSIN 
VOL SER NOS= 231401. 

SYS72144. T002347.RV000. DEBUG. S0000016 DELETED 
VOL SER NOS= 231401. 

/ START 72144.0030 

/ STOP 72144.0033 CPU 0MIN 03. 20SEC MAIN 



IEF237I 240 

IEF237I 242 

IEF237I 242 

TEF237i 241 

IEF237I 282 

IEF237I 242 

IEF237I 242 

IEF237I 137 

IEF237I 355 

IEF237I 241 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF285I 

IEF373I STEP /GO 

IEF374I STEP /GO 



52K LCS 



STEP GO ENDED. COMP CODE 00C7 CORE REQUSTED= 0052K. CORE USED= 0052K. 

IEF285I DUMMY0S KEPT 

IEF285I VOL SER NOS= DC156 . 

IEF285I PRODVER4 KEPT 

IEF285I VOL SER NOS= DC160 . 

IEF285I SYS72144.T002347.RVOOO. DEBUG. GODATA DELETED 

IEF285I VOL SER NOS= 231400. 

IEF375I JOB /DEBUG / START 72144.0024 

IEF376I JOB /DEBUG / STOP 72144.0033 CPU 0MIN 07. 96SEC 

JOB DEBUG ENDED. CODE= 00C7 JOB READ IN AT 00.40 ON 72144 JOB STRTED AT 00.41 



1.16 



ON 72144 JOB ENDED AT 00.56 



OH 72144 



Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 3 of 11) 
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?P 5734-CD2 V4 LVL76 TBI" OS AMERICAN NATIONAL STANDARD COBOL DATE JAN 6,1972 



IKF0011I-K SYSLIE NOT USABLE. COMPILATION Z O'lTItiUI NT . 
SLRDMP 7 X 

r.LEC.IP H X 



00CC1 100010 IDENTIFICATION DIVISION. 

30002 100020 PROGRAM-TO. TEST8UN. 

00003 100030 AUTHOR. FECGRAStfFR SS^v. 

00004 100040 INSTALLATION. NEW YORK PROGRAMING CENTER. 

00005 100050 DATE-SRITTEN. JUIY 12, 1968. 
.10006 100060 DATE-COMPILED. JAN 6,1972 

00QC7 100070 REMARKS. THIS PROGRAM EJAS SEEN KRITTFN AS A SAMPLE PROGRAM FOR 

00008 100080 COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK A5 

00C09 100090 INPUT. 
00010 

00011 100100 ENVIRCNfENT DIVISION. 

00012 100110 CONFIGURATION SECTION. 

00013 100120 SOURCE-CCNPUTEB. I PM-360-H50. 
100 14 100130 OBJECT-COSPUTSR. I3?i- 360-H 50. 
30C15 100140 INPUT-OUTPUT SECTTCN. 

00016 100150 FILF-CONTROL. 

00017 100160 SELECT FTLE-1 ASSIGN TO UT-2400-S-SAKPI, E. 

00018 100170 SELECT FILE- 2 ASSIGN TO UT-2400-S-SA HPI.5. 
0CC19 

00020 100 180 DATA DIVISION. 

0OC21 100190 FILE SECTION. 

00022 100200 ED FILE-1 

0CC23 100210 IABEL RECORDS ARE OMITTED 

00024 100220 BLOCK CONTAINS 100 CHARACTERS 

00025 100225 RECORD -CONTAINS 20 CHARACTERS 

00026 100230 RECORDING MODE IS F 
00C27 100240 DATA RECORD IS PECOPP-I. 
10028 100250 01 RECORD- 1. 

00029 100260 02 FIELD-A PICTURF IS X(20). 

00030 100270 FC FILE-2 

00031 100280 IABEL RECORDS ARE OMITTED 

00032 1-0-0290 BLOCK CONTAINS 5 RECORDS 
)0033 100300 RECORD CONTAINS 20 CHARACTERS 

00034 100310 RECORDING MODE IS F 

00035 100320 DATA RECORD IS RECORD-2. 

00036 100330 01 RECORD-2. 

00C37 100340 02 FIELD-A PICTURE IS X(20). 

000 38 

00C39 1C0350 HORKI NG-STOBAGE SECTION. 

00040 100360 77 KOUNT PICTURE S99 COUP SYNC. 

00C41 100370 77 NCf!8ER PICTURE S99 COHP SYNC. 

0042 100375 01 FILLER. 

00043 100380 02 ALPHABET PICTURE X(26) VALUE " ABCDEFGHIJKL«!NOPQRSTUVWXYZ" . 

00044 100395 02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

00045 100405 02 DEPENDENTS PICTURE X(26) V ALU E "0 12340 123401 23401 23401 2 34 

00046 100410- "0". 

0CC47 100420 02 DEPEND REDFFIN'S DEPENDENTS PICTURE X OCCURS 26 TT^S. 

00048 100440 01 WORK-RECORD. 

00C49 100450 02 NAHF-FIELD PICTURE X. 

00050 100460 02 FILLER PICTURE X VALUE IS SPACE. 

00051 1C0470 02 RECCRD-NO PICTURE 9999. 

00052 100480 02 FILLER PICTURE X VALUE IS SPACE. 

00053 100490 02 LOCATION PICTURE AAA VALUE IS "NYC". 

00054 100500 02 FILLER PICTURE X VALUE IS SPACF. 
00C56 100510 02 NO-CF-DEPFNDENTS PICTURE XX. 

10056 100620 02 FILLER PICTURE X(7) VALUE IS SPACES. 

J0C57 100521 01 RECCRDA. 

Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 4 of 11) 
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nnn^a 10ns?? op r A pit-turf. sq(«j vat.iif i?m. 

00C59 100523 02 B REDEFINES A PICTURE S9(7) COHPUTATTON AL- 3. 

00060 100530 PROCEDURE DIVISION. 

00C61 100540 BEGIN. HEADY TRACE. 

00062 100550 NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 
00C63 100560 AND INITIALIZES COUNTERS. 

00064 100570 STEP-1. OPEN OUTPUT FTLE-1. MOVE ZERO TO KOUNT NCKBER. 

00065 100580 NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

00066 100590 CONTAINED IN THE FILE, WRITES THEH ON TAPE, AND DISPLAYS 

00067 100600 THEH CN THE CONSOLE. 

0006" innfiin stfp-3- inn 1 Tn irniiNT. inn 1 to mohrfb. movf ALPHA (KT.'VTJ T" 

0C069 1C0620 NAHE-FIELD* 

00070 100630 HOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS. 

00071 100640 __HOVE JSCMBER TORECORD-NO^ __ _ 

015QT2 TOUTED" ST lP~-T."''T)T^irifY"1iJO¥!r-lfcoTD"Tp6N 'CONSOIE.' WRITE 'record- 1 FROM 

00C73 10C660 WCRK-EECCRD. 

00074 100670 STEP-4. PERFORM STEP- 2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 25. 

00075 100680 NCTE THAT THE FOLLOWING CLOSES OUTPUT AND RFOPFNS TT AS 

00076 100690 INPUT. 

00077 100700 STEP-5. CLOSE FILE-1. OPEN INPUT FILE- 2. 

00078 100710 NOTF THAT THE FOLLOWING READS BACK THE FILE AND STNGLFS OUT 
00C79 100720 EMPLOYEES WITH NO DEPENDENTS. 

00080 100730 STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP- 1 ?. 

00C81 100731 CCPFIJTE B = P. + 1. 

00082 100740 STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "7" TO 

00063 100750 NC-CF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

00084 100760 STEP-6. 

00085 100770 STEP-8. CLOSE FTLE-2. 

00086 100780 STOP RUN. 
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►CROSS-REP5RENCE DICTIONARY 

DATA NAHES DEFN REFERENCE 

A C0C058 

ALPHA 000044 000068 

ALPHABET 000043 

B 000059 000081 

DEFEND 000047 000070 

DEPENDENTS 000045 

FIELD-* 000C29 

FIELD-A 000037 

FILE-1 000017 000064 000072 000077 

FILE-2 000018 000077 000080 000085 

KCUNT 00004C 000064 000068 000070 000074 

LOCATION 000053 

NAHE-FIELE 000049 000068 

NO-OP-DEPENDENTS 000055 000070 000082 

HCHEEB 000041 000064 000068 000071 

RECORD-NO 000051 000071 

BECOBD-1 000C28 000072 

RECOBD-2 000036 000080 

BECOFDA C00057 

HORK-RECORD 000048 000072 000080 000083 



Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 5 of 11) 
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PflOCEDUPF NAMES 



BEGIN 1 

STEP-1 

STEP-2 

STEP-3 

STEP-4 

STFP-S 

SI2P-6 

STEP-7 

S1EP-8 



00006 1 




CC0C6U 




000068 


00007U 


C00C72 


000074 


00007 4 




C00077 




00OB0 


000 S3 


CC0082 




000 OPS 


ooooao 



20 

CA3D ERfiOR MESSAGE 

58 IKF2190I-K PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. ASSUMED POSITIVE. 

PHASE FILE1 FIIE2 FILE3 FILE4 FILS5 

1 00000000 00000000 000003UC OOCOOOOO COOOOOOO 

2 C0CC0000 00000000 00000000 00000000 00000000 

3 00000000 O00002D6 COOOOOOO COOOOOOO COOOOOOO 

4 COOOOOOO 00000000 00000000 OOOOOUOA 00000000 

5 00000000 OOOOOCOO C00002C1 COOOOOOO CCOCOOOO 

6 COOOOOOO 00000000 00000000 000003EF 00000000 

7 00000000 00000000 OOOCOOOO COOOOOOO ooocoaoo 

8 00000000 00000000 00000351 00000074 00000000 

9 000005DD 00000000 COOOOOOC COCOOOCC OOOCOOOO 
A COOOOOOO 00000000 00000000 00000000 00000000 
B 00000000 0000083C C0000035 COOOOOOO OOOCOOOO 
C 00000A34 00000000 00000246 00000001 00000000 
D 00000000 00000000 COOOOOCO COfiOCOCO OOOCOOOO 
E 00000000 00000000 00000000 00000000 00000000 
F 00000000 00000783 COOOOOCO C0C0CCE2 OOOCOOOO 
3 000001EB 00000000 00000114 00000000 00000000 
H 00000000 00000000 OOOOOOCC COOOOOOC OOOC0600 

Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 6 of 11) 
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■TESTRUN, ED1 



., -., im.«; 



'-urjucnucm^ ,Bin.ua[;-ln, 



(T)— »"81, (HEX) ,WCRK-FECCRD,E 

TESTRUN UNIDENTIFIED ELEMENTS ON CONTROL CARDS 



♦ERROR* CAFD/VERB 

IKF160I 70 IDENTIFIER NOT FOUND 



00 1 ERRORS FOUND IN CONTROL CARDS 



TESTRUN AT CARD 00007C 
LOC CARD IV NAKE 



®-0 



C0778 000040 77 KODNT 
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CCCE 

A 

AN 

ANE 

D 

DE 

F 

FD 

NE 

NB-S 

ND 

ND-OL 

ND-CT 

ND-SL 

ND-ST 

NE 

NP 

NP-S 



0D07E8 000049 02 NAME-FIELD 
0DC73A OC0C51 02 FECCFD-NC 



TYPE COPES USED IN SYMOMP OUTPUT 

MFANING 

= ALPHABETIC 

= ALPHANUMERIC 

= ALPHANUMERIC EDITED 

= DISPLAY (STFRLING NONREPORT) 

= DISPLAY EDITED (STERIING REPORT) 

= FLOATING POINT (COMP- 1/COMP- 2) 

= FLOATING POINT DISPLAY (FXTEPNAL FLOATING POINT) 

= NUMERIC BINARY UNSIGNED (COMP) 

= NUMERIC BINARY SIGNED 

= NUBFRTC DISPLAY UNSIGNED (EXTERNAL DECIMAL) 

= NUMERIC DISPLAY CVERPUNCH SIGN LEADING 

= NUMERIC DISPLAY CVERPUNCH SIGN TRAILING 

= NUMERIC DISPLAY SEPARATE SIGN LEADING 

= NUMERIC DISPLAY SEPARATE SIGN TRAILING 

= NUMERIC EDITED 

= NUMERIC PACKED DECIMAL UNSIGNED (COMP-3) 

= NUMERIC PACKED DECIMAL SIGNED 

= SUBSCRIPTED 



(HEX) 



(HEX) 



TYPE 


VALUF 


NB-S 


+ 01 




000 1 


AN 


A 


NT 


**** 




U7S0C0F 



TESTFUN IT CART 00007C 
LOC CARD LV NAME 

0D0778 0000U0 77 KOUNT 

0D07F8 000049 02 NAME-FIELD 

0DC7BA 0CC051 02 EECCEC-NC 



(HFX) 



TYPF 


VALU 


NB-S 


+ 0=. 




000 c 


AN 


E 


ND 


0004 



TESTEUN AT CARD 000070 
LCC CARD LV NAME 



0DC778 0C0040 77 KCUNT 



(HE X) 



TYPE 
NP-S 



+ 09 

0009 



0D07B8 000049 02 NAME-FIELD AN I 
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ODC/BA UCUObl U2 RSCCBD-NC 



TESTRtJN IT CARE 000070 

ICC CARD LV NAME 

0DC778 0C0040 77 KCUST 

0DC7B8 000049 02 NA£E-FIELD 

0D07EA 000051 02 RECORE-NO 



(HEX) 



TYPE 


VALU 


NP-S 


+ 13 




000D 


AN 


M 


ND 


0012 



TESTRUN AT CARD 00007C 

LOC CARD IV NAKE 

0D0778 00001*0 77 KOUNT 

0C07E8 000049 02 NAHE-FIELD 

ODC/BA 000051 02 RECCBD-NC 



(HEX) 



TYPE 
NP-S 

AN 

NT 



t17 

0011 



00 16 



TESTBUN AT CASE 000070 

LCC CARD LV NAME 

0DC778 0CC040 77 KCDNT 

0DC7 r i8 000C49 02 NAKE-FISLD 

0CC7EA 000051 02 RECORD-NO 



(HFX) 



TYPE 


VALU 


NE-S 


+ 21 




0015 


AN 


U 


NC 


0020 



TESTRUN AT CASE 00007C 
LOC CARD IV NAME 

0C0778 000040 77 KOUNT 

0D07P8 000049 02 NAME-FIELD 

0D07BA 000051 02 RECCFD-NO 



(KFX) 



TYPE 


vai.u 


Nn-s 


+ 25 




0019 


A N 


Y 


ND 


00 2 4 



(|T)-»- TESTRUN AT CARD 00008 1 

^-^ LCC CARD LV NAKE 

000048 1 SORK-FECORD 
0DC738 

0C07E8 000049 02 N AM E- f IELD 

0DC7D9 0C0050 02 FILIER 

0C07EA 000051 02 RECORD-NO 

0DC7BE 00C052 C2 FILIER 

0C07EF 000053 02 LOCATION 

0DC7C2 0C0054 02 FIIIEE 

0C07C3 000055 02 NO-OF- DFP EN DENT! 

0DC7C5 0CC056 C2 ^IIIER 

0D07T0 000059 02 ?! 



(REX) 



(HFK) 



CIUO^OFO F0F140D5 E8C340F0 



40404040 404040U0 



A N 


A 


AN 




ND 


0001 


AN 




A 


NYC 


AK 




Ml 





AN 




NF-S 


*1 *2 *3 * 




F 1F2F3CU 
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CORCT. AB^T nTinvo^Trr n.I~S 



©-■ 



CCREIETION CODE = 0C7 LAST PSS BEFORE ABEND = FFDSOOODDOODO AO 6 

(j J-*-LAST CARD NUMBER/VERE NUI<BFF EXECUTED — CARD NTJP'RS'P nnodfll/vrpp ™»'=Eo 01. 



@^TE 



FL C W TRACE 
STRUN 000068 000072 OC00P8 00C072 000068 00C072 00006H 000072 000077 000080 



DATA DIVISION D'J*F C TFSTRUN 



©- 



-TASK GLOBAL TABIE 



SAVE ARIA 



SWITCH 

TALLY 

SCET-S AVE 

ENTRY-SAVE 

SOBT-COEE-SIZ E 

HETURN-CODE 

SCFT-FFTORN 

KORKING CELLS 



SCET-FILF-SIZ E 
SORT- MODE- SIZE 
tGT-VN TEL 
TGT-VN TPL 
VCCN ACtF 
\N TBL TFV'tii 
IAEFL PFTO:. 
CURRENT PRIORITY 
IE PUG S AVE 11 
COBOL INDICATOR 
t. (INIT1) 

DEBUG TABLE PIP 
SUECOP! SEER 
SORT DDNAHE 
UNUSEC 
DEBUG SAVE 11 
UNUSEE 
PRBADR CFLL 
GENCE T AELF. 
INLSED 

TRANSIENT AREA LENGTH 
EN USED 

CVEEFLCH CELLS 
BL CELLS 
IECEAIB CEILS 
TEMP STORAGE 
EIL CELLS 



LCC 

0D0938 
0D0958 
0D0978 
0DC980 
0D0984 
CD0988 
0P098C 
0D0990 
000994 
0D0996 
0D0998 
CD09E8 
0n09D8 
0D09F8 
ODOA 18 
0P0A38 
ODOA 1 ;? 
0D0A7R 
ODOA 98 
DO ADS 
0D0AC8 
ODOACC 
ODOA DO 
OOOATW 
0O0AD8 
ODOACC 
ODOADE 
ODOADF 
ODOAEO 
0D0AF4 
0D0A58 
ODO AF.C 
OPOAFO 
0D0AF4 
ODOAFC 
0D0P10 
0DOB14 
0D0P18 
CD0B1C 
0D0B20 
0D0321 
0D0B24 
(NONF) 
0D0B2C 
(NONF) 
0D0B38 
0DCB40 



V ALUF 

009A9200 000DC768 000DA2F8 700D0FB6 

0002SCE" OOCOOODO 700T0E0F 000DO778 

700nO n .C' ? . 000R0B70 

7F)00C04R 

00000000 

CCOCCOOO 

000 TO HDC 

COOCOOOO 

OSFF 

c eg i 

O0Or24S6 000H2F1A yf vv ??2F. O00DC7 i: '8 

F2F' : 40OS T7 8C3U0F0 0200U020 4040404C 

PC031B99 S0910000 U1U0C0EA 47F0C1*8 

7000DC00 18E00700 FA306058 C04F070C 

20001000 30C00000 000A778R OOOOOOOO 

0O0D080C 010090EC 400D0F84 000D1CPA 

CCOCOOOC 700D0E0E 000^0778 090"A414 

000C0P70 OO0COE9E 000MC8A 00000030 

427CB001 92U0B002 92003003 43405000 

E00841E0 P00C41C7 C0014177 "C019102 

OCCCOOOO 

OOOOOOOO 

8*029142 

SO EO COOP 

5C5CD0 0C 

4177 

CC 

00 

7 n T; ;CE 

A NS C 

0C0O06F0 

00000478 

0C0D0630 

565CD000 OOCCOOOO 1F744100 000C1815 

000 TO FTC 

C0011815 

ooo no pp8 

DC061FD2 

Oh 

7FQ^00 

50049600 90024140 

000DA414 O00DA4O0 0O0D0778 

OOOOOOOO 0000026C 
OCCCOOCO OOCCOOOO 



0O00E23A 700C0ECE 000DA400 0O0DO8B8 
000DA414 000DA400 OOODOFFF 000DC6F0 



0002635:: OOOOOOOO 00108000 E940F0 , = , 

000D06F0 000CO6FO 000O0R70 60089202 

D2001000 ^0000200 D05840C0 D700D058 

6800D1D8 07FP4000 OOOOOFAO 000DC658 

00000001 00OA7BC0 47F0F0CF 0OODOE96 

00000030 000D0E9E 000D080C 00026C<='4 

000C06F0 OOOEOF^F OOOPO^'O 00ODC3DC 

8E0O r :020 OOODOSOC 00011 A7« OOODO^fi 

444090W 5060B00U 06704470 917A50C0 



58505004 
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)IYTSI05 T>!7ME O w TESTPQN 



VLC CEILS (NCNE) 

SEL CELLS (NONE) 

INDEX CEILS (NONE) 

OTHER {SEE MEMOBY HAP) 0D0BU8 
CD0P68 



000D0799 000D07B3 000D0D90 OOOD0D90 
GA0CC8CA 20C60A0A 



800D08B8 181U1E11 4101100C 00000001 



DATA DIVISION OU^F OF TF3TRHN 



®- 



LOC CABD IV NAKE 
*-000017 EC FILE-1 



OD C 8 CC 
0DCS2C 
0D084C 



^v 0CC028 01 FECCED-1 

(N)-»-0EJ414 000029 02 FIELD-A 



w 


•-0C0018 


FD 


FIIE-2 




0E08E8 










0D08D8 










0DC6F8 










®^ 


000036 


01 


FECORE- 


-2 


•->. ^CDA4GC 
( P)-»-0E0778 
^^ 0DC77A 


0C0C37 


02 


FTEID-, 


A 


OOOOHO 


77 


KOUNT 




0C04.1 


77 


NCHBEF 






000042 


01 


FILLFR 




0DC780 


00004 3 


02 


alphas: 


FT 




000044 


02 


ALPHA 




(llWoE07 80 
V - X 0D0781 








(STJP1) 
1 
2 


0DC782 








3 


0E0783 








4 


0DC784 








5 


0E0785 








g 


0DC786 








7 


0E0787 








8 


0DC788 








o 


0C0789 








10 


0DC78A 








11 


E078P 








12 


OD C 7 8C 








13 


0E078E 








1U 


0DC78F 








15 


0E078F 








16 


0DC7=C 








17 


0D079 1 








18 


0DC792 








19 


0E079 3 








20 


0DC794 








21 


0E0795 








22 


0DC796 








23 


0C0797 








24 



TYPF VALUE 

QSA* FILE: CLOSED ORGANIZATION: PHYSICAL SEQUENTIAL 



C0000000 00000000 00000000 0000000^ 
46000001 900D07DC E2C1D4D7 D3C54040 
C0C00000 00000000 00000000 00000001 



00810000 000DA391 O0C04000 00000001 
02000048 00000001 060D2456 00000064 
00000014 00000001 00000000 00000000 



AN ? 0002 NYC 1 

QSAR FTL^: OPFN ORGANIZATION: PHYSICAL SECUFNTTPL 



DCB 00000000 00000000 00000000 00000002 

460D0FC8 900D0888 007C4800 00026CE4 
28012828 000DBC30 000DA464 00ODA4OO 



00R1C300 020DA390 00004000 0000000 1 
120FFF00 000FFC40 060D2456 00090064 
00000014 00000001 00000000 000FF898 



AN 

KB-S 

NE-S 



AN 
*AN 



A 00 1 NYC 
+ 26 
+ 26 



ABCnFFSHIJKLKNOPQHSTtlVWXyZ 
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DATA DIVISION DUMP CF TESTRUN 



LCC 


LJSD 


1 V 


WAPK 


0D0798 






25 


0DC799 






26 


0D079 A 


0000(t5 


02 


DFPENEENTS 




C G C '4 " 


02 


DEFEND 


0DC79A 




(0/ MSUB1) 

1 


0EC79F 






2 


L07 9i_ 






3 


0DC79D 






4 


0E079E 






q 


nnr7QT 






-§--- 


0D07 AO 






7 


0DC7A1 






8 


0D07J2 






9 


0DC7A3 






10 


0E07A4 






11 


0DC7A5 






12 


0CO7.A6 






13 


0DC7A7 






14 


0C07A8 






15 


ODC7A9 






16 


0D07AA 






17 


ODC7AB 






18 


0DO7 AC 






19 


0DC7AD 






20 


0E07AE 






21 


0DC7AF 






22 


0E07E0 






23 


0DC7B1 






24 


0C07E2 






25 


0DC7B3 






26 




000048 


01 


WORK-KECORE ■* 


0DC7B8 


000049 


02 


NAKE-FIELD 


OE07E9 


000050 


02 


FILLER 


0DC7BA 


0C0051 


02 


RECCRD-NC 


0E07EE 


000052 


02 


FILLE3 


0DC7BF 


0CC053 


02 


ICCATICN 


0D07C2 


000054 


02 


FILLER 


0D07C3 


000055 


02 


NC-CF-DEFSRDENTS 


0E07C5 


000056 


02 


FILLER 




000057 


01 


FECOBDA 


0C07E0 


000058 


02 


A 


0DC7D0 


000059 


02 


R 



AN 
*AN 



AN 

AN 

NT 

A N 

A 

AN 

AN 

AN 



ND-OT 
NP-S 



Y 
Z 
12340 1 2 J40 12340 12 340 12 34 



000 1 



(HEX) 



+ 1234 
* 1* 2* 3* 
F1F2F3C4 



— <i) 



DATA DIVISION DITKP OF TFSTRUN 



CAFE LV NAME 



TYPE VALU" 



=ND OF C060L DIAGNOSTIC AIDS 

Figure 51. Using the SYMDMP Option to Debug the Program TESTRUN (Part 11 of 11) 
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OUTPUT 



The compiler, linkage editor, COBOL load 
module, and other system components can 
produce output in the form of printed 
listings, punched card decks, diagnostic or 
informative messages, and data sets 
directed to tape or mass storage devices. 
This chapter describes the output listings 
that can be used to document and debug 
programs and the format of the output 
modules. The same COBOL program is used 
for each example. "Appendix A: Sample 
Program Output" shows the output formats in 
the context of a complete listing generated 
by a sample program. 



• System messages 

• Disposition messages from the job 
scheduler 

• An object module 

• A cross-reference listing 

• A condensed listing containing source 
card numbers and the location of the 
generated instruction for each verb 

• Compiler statistics 



COMPILER OUTPUT 



The output of the compilation job step 
may include: 



Diagnostic messages associated with the 
compilation of the source program are 
automatically generated as output. The 
other forms of output may be requested in 
the PARM parameter in the EXEC statement. 
The level of diagnostic messages printed 
depends upon the FLAGW or FLAGE options. 



• A printed listing of the job control 
statements 

• Device allocation and deallocation 
messages from the job scheduler 

• A printed listing of the statements 
contained in the source module 

• A glossary of compiler-generated 
information about data 

• A printed listing of the object code 

• Compiler diagnostic messages 



© 



All output to be listed is written on 
the device specified by the SYSPRINT DD 
statement. Line spacing of the source 
listing and the number of lines per page 
can be controlled by the SPACEn and LINECNT 
options. 



Figure 52 contains a portion of the 
compiler output listing shown in "Appendix 
A: Sample Program Output. " Each type of 
output is numbered, and each format within 
each type is lettered. The text following 
Figure 50 is an explanation of the 
illustration. 



//TEST JOB 
//JOBLIB DD 
//STEP! EXEC 
//SYSUT1 DD 
//SYSUT2 DD 
//SYSUT3 DD 
//SYSUT4 DD 
//SYSLIN DD 
// 

//SYSPRINT DD 
//SYSIN DD 



NY83922041 ,'A. HALL ' ,MSGLEVEL= ( 1 , 1 ) ,CLASS=C ,MSGCLASS = U 
DSN=PR0DVER4,DISP=SHR,V0LUME=SER=USAS,UNIT=2 314 
PGM=IKFCBL00,PARM='DMAP,PMAP,XREF,QU0TE,0PT' ,REGI0N=76K 
DSNAME = &&UT1 ,UN IT = SYSDA ,SPACE=(TRK , ( 100 ,10 ) ) 
DSNAME=&&UT2,UNIT=SYSDA,SPACE=(TRK,(100,10)) 
DSNAME=&&UT3,UNIT=SYSDA,SPACE=(TRK,( 100,10)) 
DSNAME=&&UT4,UNIT=SYSDA,SPACE=(TRK,(100,10)) 
DSNAME=&&PNCH,UNIT=SYSDA,SPACE=(TRK,(100,10)) , X 

DISP=(NEW,PASS) 
SYS0UT=U 



IEF236I ALLOC. FOR TFSTRUN COB 



® 



IEF237I 23T 

IEF237I 230 

IEF237I 235 

IFF237I 230 

IEF237I 242 

IEF237I 230 

IFF237I 235 

IEF237I 243 

IFF237I 235 



ALLOCATFD 
ALLOCATFD 
ALLOCATED 
ALLOCATED 
ALLOCATED 
ALLOCATFn 
ALLOCATED 
ALLOCATED 
ALLOCATED 



TO SY 
TO SY 
TO SY 
TO SY 
TO SY 
TO SY 
TO SY 
TO ST 
TO SY 



SPRINT 
SUOUMP 

sun 

SUT2 

SUT3 

SUT4 

SLIN 

EPLIB 

SIN 



Figure 52. Examples of Compiler Output (Part 1 of 3) 
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00001 100010 IDENTIFICATION DIVISION. 

00002 100020 PROGRAK-ID. TESTRUN. 
UUUUJ 100030 AUTHOR. PROGRAMMER NAME. 

00004 100040 INSTALLATION. NEW YORK PROGRAMMING CENTER. 

00005 100050 DATE-WRITTEN. JULY 12, 1968. 

00006 100060 DATE-CCMPILED. FEB 19,1972 







00018 100180 DATA DIVISION. 

00019 100190 FILE SECTION. 

00020 100200 FD FILE-1 

00021 100210 LABEL RECORDS ARE OMITTED 

00022 100220 3L0CK CONTAINS 100 CHARACTERS 

00023 100225 RECORD CONTAINS 20 CHARACTERS 
UUU^M lUUijU KJSCUKD1NU MUU1S lb f" 

00025 100240 DATA RECORD IS RECORD-1. 

0002b 100250 01 RECORD-1. 

00027 100260 02 FIELD-A PICTURE IS X(20». 

00028 100270 FD FILE-2. . . ... 



00057 100530 PROCEDURE DIVISION. 

00058 100510 BEGIN. READY TRACE. 

00059 100550 NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

00060 100560 AND INITIALIZES COUNTERS. 

00061 100570 STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NOMBER. 



00078 100730 STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP- 8. 

00079 100740 STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE "Z" TO 

00080 100750 NO-OF-DEPENDENTS. EXHIEJT NAMED WORK-RECORD. GO TO 

00081 100760 STEP-6. 

00082 100770 STEP-8. CLOSE FILE-2. 

00083 100780 STOP RUN. 







© 



® © 

INTRNL NAME LVL SOURCE NAME 



J DNM=1- 


118 


FD 


FILE-1 




l DNM=1-167 


01 


RECORD-1 




1 DNM=1-188 


02 


FIELD-A 




1 DNM=l-205 


FD 


FILE-2 




< DNM=l-224 


01 


RECORD- 2 




) DNM=l-245 


02 


FIELD-A 




1 DNM=l-265 


77 


KOUNT 




\ DNM=2-071 


02 


B 




/ 


S 


HFHnRY 1*P 








TGT 




00248 




SAVE AREA 
SWITCH 
TALLY 
SORT SAVE 




002U8 
00290 
00294 
00298 




ENTRY- SAVE 


0029C 




XSASW CELLS 
1 XSA CELLS 


00478 
00478 



© 



PGT 

OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
DCB ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERALS 



00498 

00498 
00498 
004B8 
004CC 
004E4 
004EC 
004F0 
00504 



$ © © 



® 



© © 



© 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


DCB=01 




DNM=1-148 




QSAM 


BL=1 


000 


DNM=1-167 


DS 0CL20 


GROUP 


BL=1 


000 


DNM=1-18 8 


OS 20C 


DISP 


DCB=02 




DNM=l-205 




QSAM 


BL=2 


000 


DNM=l-224 


DS 0CL20 


GROUP 


BL=2 


000 


DHM=l-245 


DS 2CC 


DISP 


BL=3 


000 


DNM=l-26 5 


DS 1H 


COKP 


BL=3 


058 


DNM=2-071 


DS 4P 


COMP- 3 



ROQM 



B) LITERAL POOL (HEX) 

004F0 (LIT+0) 00000001 1C00001A 00U805EF 48000000 

DISPLAY LITERALS (BCD) 
00504 (LTL+20) 'WORK-RECORD' 



© 



Register »ssignmen' 

' REG 6 BL =3 
| REG 7 BL =1 

REG 8 BL =2 



WORKING-STORAGE STARTS AT LOCATION 00088 FOR A LENGTH OF 00060 



S ® Q ® 



©00 







© 



000510 




000510 


07 00 


000512 


58 FO C O0C 


000516 


05 EF 


000518 


58 F0 C 010 


00051C 


05 IF 


00051E 


0000003A 


000522 


58 F0 C 014 


000526 


05 IF 


000528 


000140 


00052E 


05F5F840404040 


000532 


96 40 D 048 


000536 


58 F0 C 00C 


00053A 


5 EF 


00053C 


58 F0 C 010 


000540 


05 IF 


000542 


0000003D 


000546 


58 F0 C 014 


00054A 


05 IF 


00054C 


000140 


00054F 


05F6F140404040 


000556 


58 F0 C 00C 


0OC55A 


03 EF 



EQU 


* 




BCR 


0,0 




L 


15, 00C(0, 12) 


V(ILBODBG4) 


BALR 


14,15 




L 


15,010(0, 12) 


V(ILEOFLWl) 


BALR 


1,15 




DC 


X'0000003A' 




L 


15,014(0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X' 000140' 




DC 


X , 05F5F840404040" 




OI 


048(13), X'40" 


SWT+0 


L 


15,OOC(0, 12) 


V(ILBODBG4) 


BALR 


14,15 




L 


15, 010(0, 12) 


V(ILBOFLWl) 


BALR 


1,15 




DC 


X-0000003D' 




L 


15,014 (0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X'000140' 




DC 


X , 05F65140404040" 




L 


15,00C(0,12) 


V(ILBODBG4) 


BALR 


14,15 





Figure 52. Examples of Compiler Output (Part 2 of 3) 
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( *STATISTICS* SOURCE RECORDS = SH DATA DIVISION STATEMENTS = 2 5 PROCEDURE DIVISION STATEMENTS = 

®) *OPflONS IN EFFECT* SIZE = 81920 EUF = 27b8 LINECNT = 57 SFACEi, FLAGW, 3EQ, SOURCE 
\ +OPTIONS IN EFFECT* DMAP, PMAP, NOCLIST, NOSUPKAP, NOXREF, SXREF, LOAD, NODECK, QUOTE, NOTRUNC, FLOW= 

( *OPTIONS IN EFFECT* NOTERM, NONUM, NOBATCH, NONAME, COKPILE=01, STATE, NORESIDENT, NODYNAM, NOLIB, NOSYNTAX 

CROSS-REFERENCE DICTIONARY 



DATA NAMES 



FIELD-A 

FIELD-A 

FILE-1 

FILE- 2 

KOUNT 

LOCATION 

NAME-FIELD 

NO-OF-DEPENDENTS 



3EFN 


RFFERFNCE 






000027 










000035 










00001b 


000061 


000070 


000075 




000017 


000075 


000078 


000082 




000037 


000061 


000065 


000068 


000072 


000050 










00001b 


000065 








000052 


000068 


000079 







I PROCEDURE NAMES 



BEGIN 
3TEP-1 
STEP- 2 
STEP- 3 




DEFN 


REFERENCE 


000038 




000061 




000065 


000072 


000070 


000072 


000082 


000078 


ERROR MESSAGE 



IKF11001-W 
IKF2190I-H 



2 SEQUENCE ERRORS IN SOURCE PROGRAM. 

PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. 



ASSUMED POSITIVE. 



SYS71023.T0112O9.RVO00.TESTRUN.GODATA PASSEO 

VOL SER N0S= 0DB116. 

SYS71'323.T01121<>.SV9' , ?.TESTRUN.R0000011 DFLETED 

VOL SFR NOS= 23W>. 

SYS71O23.T011209.SVO0-).TFSTRUN.R0O1O012 SYSOUT 

VOL SFR NOS= 2 31400. 

SYS7n23.T011209.RV0CO.TFSTRUN.R00i0113 DELETED 

VOL SER NOS= L00300. 



Figure 52. Examples of Compiler Output (Part 3 of 3) 



1 . L isting of j ob co ntrol state ments 

as s ociated w ith t his job step. These 
statements are listed because 
MSGLEVEL=(1,1> is specified in the JOB 
statement. JCL statements with XX 
instead of // represent statements in 
a cataloged procedure. 

2 • Allocation messag es from the job 
scheduler. These messages provide 
information about the device 
allocation for the data sets in the 
job step. They appear after the job 
control statements in the compile, 
linkage edit, and execution job steps. 
For example : 

IEF237I 235 ALLOCATED TO SYSUTl 

indicates that the data set for SYSUTl 
has been assigned to the device 235. 

3» Source module listing. The statements 
in the source module are listed 
exactly as submitted except that a 
compiler-generated card number is 
listed in the first column of each 
line. This number is referred to in 
diagnostic messages, on the XREF or 
SXREF listing, and in the object code 
listing. If NUM is specified, the 



programmer-encoded source numbers in 
columns 1 through 6 are used in each 
of these cases. (See the description 
of the NUM option under "Options for 
the Compiler.") The source module is 
not listed when the NOSOURCE option is 
specified. 



The following notations may appear on 
the listing: 

C Denotes that the statement was 
inserted with a COPY statement. 
Statements copied will not be listed 
if SUPPESS is indicated. 



** Denotes that the card is out of 
sequence. 

I Denotes that the card was inserted 
with an INSERT card. 

If DATE-COMPILED is specified in the 
Identification Division, any sentences in 
that paragraph are replaced in the listing 
by the date of compilation in the following 
format: 

DATE-COMPILED. month day, year 
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Glossary : The glossary is listed when 
the DMAP option is specified. The 
glossary contains information about 
names in the COBOL source program. 



A and F„ The internal name generated 
b^ the compiler. This name is 
used in the compiler object code 
listiag to r-e-present- fefee -aafse Ursed 
in the source program. It is 
repeated for readability. 

B. A normalized level number. This 
level number is determined by the 
compiler as follows: (1) the 
first level number of any 
hierarchy is always 01, and 
increments for other levels are 
always by one; (2) only level 
numbers 03 through 49 are affected 
— level numbers 66, 77, as well 
as 88 and FD, SD, RD, and CD 
indicators are not changed. 

C. The data name that is used in the 
source module. 



D and E. For data names, these 

columns contain information aoout 
the address in the form of a base 
and displacement. For file names, 
the column contains information 
about the associated DCB and DECB, 
if any. 



:> V> - . ~. .._-^-^ ' 
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each data item. It is represented 
in assembler-like terminology. 
Table 21 refers to information in 
this column. 



H. Usage of the data name. For FD 
entries, the file processing 
technique is identified (e.g. 
QSAM, BDAM, etc. ) . For group 
items, GROUP is identified. For 
elementary items, the information 
in its USAGE clause is identified, 
or the USAGE that was specified on 
its group. 

I. A letter under column: 



Note that the following Report Writer 
internally generated data-names can 
appear under the SOURCE NAME column: 

CTL.LVL Used to coordinate control 

break activities. 
GRP.IND Used by coding generated 

for GROUP INDICATE 

clause. 
TER. COD Used by coding generated 

for TERMINATE statement. 
FRS.GEN Used by coding generated 

for GENERATE statement, 
-nnnn Generated report record 

associated with the file 

on which the report is to 

be printed. 
RPT.RCD Build area for print record 
CTL.CHR First or second position of 

RPT.RCD. Used for 

carriage control 

character. 
RPT.LIN Beginning of actual 

information that will be 

displayed. Second or 

third position of 

RPT.RCD. 
CODE-CELL Used to hold code specified 

in CODE clause. 
E. nnnn Name generated from COLUMN 

clause in a level-02 

statement. 
S.nnnn Used for elementary level 

with SUM clause, but not 

with data-name. 
N. nnnn Used to save the total 

number of lines used by a 

report group when 

relative line numbering 

is specified. 



R-Indicates that the data-name 
redefines another data-name. 

O-Indicates that an OCCURS clause 
has been specified for that 
data-name. 

Q-Indicates that the data-name is 
the object or contains the 
object of the DEPENDING ON 
option of the OCCURS clause. 

M-Indicates that the format of the 
records of the file is: 

F = fixed 
V = variable 
U = undefined 
S = spanned 

I-Indicates an input CD in a 
teleprocessing application 

O-Indicates an output CD in a 
teleprocessing application 

5. Global Tables and Li teral Pool: The 
global table is listed when the PMAP, 
CLIST, or DMAP option is specified 
unless SUPMAP is also specified and an 
E-level diagnostic message is 
generated. A global table contains 
easily addressable information needed 
by the object program for execution. 
For example, in the Procedure Division 
source coding (3), the address of the 
first instruction under STEP-1, 
namely: 

OPEN OUTPUT FILE-1. 

would be found in the PROCEDURE NAME 
CELLS entry of the Program Global 
Table (PGT). 
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A. Task Global Table (TGT). This 
table consists of switches, 
addresses, and work areas whose 
information changes during 
execution of the program. 

B. Literal Pool. The literal pool 
lists the collection of the 
literals in the program, with 
duplications eliminated. These 
literals include those specified 
by the programmer (e.g., MOVE 
"ABC" TO DAT A- NAME) and those 
generated by the compiler (e.g.. 
to align decimal points in 
arithmetic computation). The 
literals are divided into two 
groups: those that are referred 
to by instructions (marked 
"LITERAL POOL") and those that are 
referred to by the calling 
sequences to object time 
subroutines (marked "DISPLAY 
LITERALS" ) . 

C. Program Global Table (PGT). This 
table contains the remaining 
addresses and the literals used by 
the object program. 

For further discussion, see 
"Appendix J: Fields of the Global 
Table. " 



procedure-names and verb-names are 
listed with the associated code. 



C. The relative location, in 
hexadecimal notation, of the 
object code instruction in the 
module. 

D. The actual object code instruction 
in hexadecimal notation. 

E. The procedure-name number. A 
number is assigned only to those 
procedure-names to which reference 
is made in other Procedure 
Division statements. This may be 
a PN (procedure-name) or GN 
(generated-name) number. 

F. The object code instruction in a 
form that closely resembles 
assembler language (with 
displacements in hexadecimal 
notation) . 

G. Compiler-generated information 
about the operands of the 
generated instruction. This 
includes names and relative 
locations of literals. Tables 21 
and 22 refer to information in 
this column. 



6. R egister Assignment : This contains 
the register assigned to each base 
locator (BL) in the object program. 

7 « Working - Stor age : When PMAP, CLIST, or 
DMAP is specified, both the location 
and the length (in hexadecimal) of the 
Working-Storage Section, if any, are 
provided. 

8 * Objec t Code Listing: The object code 
listing is produced when the PMAP 
option is specified unless SUPMAP is 
also specified and an E-level error is 
encountered. The actual object code 
listing contains: 



A. 



B. 



The compiler-generated card number 
or source card number, if NUM is 
specified. The number refers to 
the COBOL statement in the source 
module that contains the verb 
listed under column B. 

The relative verb number for each 
card number. 

The statement within which the 
COBOL verb appears determines the 
information under columns C, D r F, 
and G. 

If VERB is specified in 
connection with PMAP or CLIST, 



Note : The programmer can produce a 
condensed listing by specifying CLIST 
as an option in place of PMAP. The 
CLIST option produces only the source 
card number, the relative verb number, 
and the location of the first 
generated instruction, as follows: 
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VERB1 00 04 AC 


58 VERB1 000UC0 


58 


VERB2 0004F2 


62 VERBl 00050E 


62 


VERB2 00051A 


62 VER33 000526 


9. 


Statistics: The 


compiler statistics 




list the options 


in effect for this 



run and the number of Data Division 
and Procedure Division statements 
specified. Each level number is 
counted as one statement in the Data 
Division. Each verb is counted as one 
statement in the Procedure Division. 

10. Cross-Reference Dictionary : The XREF 
dictionary, produced when either the 
XREF or the SXREF option is specified, 
consists of two parts: 

A. The XREF dictionary for data-names 
followed by the generated number 
or source card number of the card 
on which the statement begins, if 
NUM is in effect. For condition 
names, the data- name of the 
conditional variable appears in 
the XREF dictionary. 
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B. The XREF dictionary for 

procedure-names followed by the 
generated number or source card 
number of the card on which the 
statement begins. 

For XREF, all the names begin in the 
order in which they are defined in the 
source program. For SXREF, the names 
appear sorted _in __ alphanumeric, order. 
The number of references appearing for 
a given name is based on the number of 
times the name is referenced in the 
compiler-generated code. 



11. Dia gnostic me s sages : The diagnostic 
messages associated with the 
compilation are always listed. The 
format of the diagnostic message is: 

A.. Compiler-generated line number or 
source card number. This is the 
number of a line in the source 
module related to the error. 

Note : In this listing of TESTRUN, 
there were no error messages. 
However, a typical message is 
provided with the compiler output 
to serve as an example of message 
format. 

B. Message identification. The 
message identification for COBOL 
compiler diagnostic messages 
always begins with the symbols 
IKF. 

C. Severity level. There are four 
severity levels as follows: 

W Warning -- This severity level 
indicates that an error was 
made in the source program. 
However, it is not serious 
enough to hinder the execution 
of the program. These warning 
messages are listed only if 
FLAGW is specified. 

C Conditional — This severity 
level indicates that an error 
was made but that the compiler 
makes an assumption, which in 
some cases corrects the error. 
The statement containing the 
error is retained. Execution 
can be attempted for its 
debugging value. 

E Error — This severity level 
indicates that a serious error 
has been detected. Usually the 
compiler makes no corrective 
assumption. The statement or 
operand containing the error is 
dropped. Execution of the 



program should not be 
attempted. 



Disaster -- This severity level 
indicates that a serious error 
was made. Compilation is not 
completed. Results are 
unpredictable. 



There is a correlation between 
severity level and the return 
codes referred to by the COND 
parameter. For example, a 
compilation in which a W-level 
error is detected generates a 
return code of 1; a C-level error, 
a code of 8; an E-level error, of 
12; and a D-level error, of 16. 



D. Message text. The text identifies 
the condition that caused the 
error and indicates the action 
taken by the compiler. 



Since Report Writer generates a 
number of internal data items and 
procedural statements, some error 
messages may reflect internal 
names. In cases where the error 
manifests itself mainly in these 
generated routines, the error 
messages may indicate the card 
number of the RD entry for the 
report under consideration. In 
addition, there are errors that 
may indicate the card number of 
the card upon which the statement 
containing the error ends rather 
than the card upon which tne error 
occurred. Messages for errors in 
the files refer to the card number 
of the associated SELECT clause. 
Internal name formats for Report 
Writer are discussed in the 
"Glossary. " 
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On a given page of the listing, 
all messages beginning with the 
symbols 'IKF6' follow all other 
messages, as in the example below. 



numbers of volumes in which the data 
sets reside. 



CARD ERROR MESSAGE 



IKF1015I-E 



ERROR MESSAGE 



IKF6006I-E 



EXTERNAL NAME IN 

SYSTEM- NAME ***** 
INVALID. 

SYSTEM-NAME IGNORED. 



SUPMAP SPECIFIED AND 
E-LEVEL DIAGNOSTIC 
HAS OCCURRED. . . . 



12. 



A complete list of compiler 
diagnostic messages is contained 
in the Program Product publication 
IBM OS F ull Am erican National 
Standard COBO L, Version 4 
Messages . 

Disposit ion m e ssages from the job 
scheduler: These messages contain 
information about the disposition of 
the data sets, including volume serial 



OBJECT MODULE 



The object module contains the external 
symbol dictionary, the text of the program, 
and the relocation dictionary. It is 
followed by an END statement that marks the 
end of the module. For more detailed 
information about the external symbol 
dictionary, text, and relocation 
dictionary, see the publication IBM_OS 
Linkage Editor and Loader. 

An object module deck is punched if the 
DECK option is specified unless SUPMAP is 
specified and an E-level diagnostic message 
is generated, and if a SYSPUNCH DD 
statement is included. An object module is 
written in an output volume if the LOAD 
option is specified unless SUPMAP is 
specified and an E-level diagnostic message 
is generated, and if a SYSLIN DD statement 
is included. 



Table 21. Glossary Definition and Usage 

r ~ ■ :-~~ T 

| Type | Definitiona- 

l- 



Usage 



Group Fixed Length 
Alphabetic 
Alphanumeric 
Alphanumeric Edited 
Group Variable Length 
Numeric edited 
Sterling Report 
External Decimal 
External Floating Point 
Internal Floating Point 

Binary 

Internal Decimal 

Sterling Non-Report 

Index-Name 

File (FD) 

Condition (88) 

Report Definition (RD) 

Sort Definition (SD) 



DS OCLN 
DS NC 
DS NC 
DS NC 
DS VLI=N 
DS NC 
DS NC 
DS NC 
DS NC 
DS IF 2 or 



4C 



DS ID 2 or 8C 

DS 1H 2 , IF 2 , 2F 2 , 2C, 4C, 8C 

DS NP 

DS NC 

BLANK 

BLANK 

BLANK 

BLANK 

BLANK 



GROUP 

DISP 

DISP 

AN-EDIT 

GROUP 

NM-EDIT 

RPT-ST 

DISP-NM 

DISP-FP 

COMP-1 

COMP-2 

COMP 

COMP-3 

DISP-ST 

INDEX- NAME 

FILE PROCESSING TECHNIQUE 

BLANK 

BLANK 

BLANK 



i In this column, N = size in bytes, except in group variable length where it is a 

variable-length cell number. 
2 If the SYNCHRONIZED clause appears, these fields are used. 
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Table 22. Symbols Used in the Listing and Glossary to Define Compiler-Generated 
Information 



Symbol 



Def; 



.on 



T 



DNM 

SAV 

SA.V2 

SAV3 

SWT 

WC 

TS 

TS2 

TS3 

TSU 

VLC 

SBL 

BL 

BLL 

ON 

PFM 

PSV 

VN 

DEC 

SBS 

XSW 

XSA 

PRM 

PN 

GN 

DCB 

VNI 

LTL 

I NX 

V(BCDNAME) 

RSV 

3SV 

CKP 

PBL 



Source Data Name 
Save Area Cell 
Input/Output Error Save Cell 
OPEN Parameter 

Sw itc h Cell 

Tally Cell 

Working Cell 

Temporary Storage Cell 

Temporary Storage (Non- Arithmetic) 

Temporary Storage (Synchronization) 

Temporary Storage (Table-Handling) 

Variable Length Cell 

Secondary Base Locator 

Base Locator 

Base Locator for Linkage Section 

On Counter 

Perform Counter 

Perform Save 

Variable Procedure Name 

DECB Address 

Subscript Address 

Exhibit Switch 

Exhibit Save Area 

Parameter 

Source Procedure Name 

Generated Procedure Name 

DCB Address 

Variable Name Initialization 

Literal 

Index Cell 

Virtual 

Report Save Area 

Sort Save Area 

Checkpoint Counter 

Procedure Block (Optimizer) 



T 



LINKAGE EDITOR OUTPUT 

The output of the linkage editor job 
step may include: 

• A printed listing of the job control 
statements 

• A map of the load module after it has 
been processed by the linkage editor 

• A cross-reference list 

• Informative messages 

• Diagnostic messages 

• Disposition messages 

• A listing of the linkage-editor control 
statements 



• A load module that must be assigned to 
a library 



Any diagnostic messages or informative 
messages associated with the linkage editor 
are automatically generated as output. The 
other forms of output may be requested by 
the PARM parameter in the EXEC statement. 
All output to be listed is written in the 
data set specified by the SYSPRINT DD 
statement. 



Figure 53 is an example of linkage 
editor output listing. It shows the jojd 
control statements, informative messages, 
and module map. The different types of 
output are numbered and each type to be 
explained is lettered. The text following 
Figure 53 is an explanation of the 
illustration. 
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XXLKED EXEC PGM= IEWL . PARM=( XREF.L I ST, LET ) ,COND=( 5, LT, COB) , 

XX REGI0N=96K 

XXSYSLIN OD OSNAMF=ELOAOSET,DISP=<OLD, DELETE) 

XX 00 ODN»MF=SYSIN 

XXSYSLMOD 00 OSNAME=£GOOATA (RUN > , DISP=< NEW, PASS I , 

XX UNIT=SYSDA,SPACE=<1024,(50,20,1) ) 

XXSYSLIB OD 0SN=SYS1.C0BULIB,DISP=SHR 

XXSYSUT1 00 IINIT=(SYSDA,SFP=(SYSLIN,SYSLM0DI>, 

XX SPACE=U024,(50,20)I 

XXSYSPRINT DO SYSOUT=A 

XXSYSUDUMP 0.0 SYSmiT=A 



X00000100 
00000110 
00000120 
00000130 

X00000140 
00000150 
00000160 

X00000170 
00000180 
00000190 
00000200 



(?) 



© 



IEF236I ALLOC. FOR TESTRUN LKFO 

IEF237I 235 ALLOCATED TO SYSLIN 

IEF237I 2*2 ALLOCATED TO SYSLMOD 

IFF237I 243 ALLOCATED TO SYSLIB 

IEF237I 230 ALLOCATED TO SYSUT1 

IEF237I 230 ALLOCATED TO SYSPRINT 

IEF2 37I 230 ALLOCATED TO SYSUOUMP 



F88-LEVEL LINKAGE EDITOR OPTIONS SPECIFIED XRFF,LI ST, LET 
VARIABLE OPTIONS USED- S IZ E={ 90112, 16384)- 



OEFAULT OPTION! SI USED 



© 



© 



© 




CONTROL SECTION 




NAME ORIGIN 


LENGTH 


TFSTRIJN 00 
ILBOOSPO* 800 
ILBOERRO* EA8 


800 
6A6 
1F6 



© 



CROSS REFFPENCE TABLE 



ENTRY 

NAME LOCATION 



ILB0ERR1 
ILB0FRR5 



ILBOSTPO* 1090 35 

ILBOSTPl 

® © © 

LOCATION REFERS TO SVMBOL IN CONTROL SECTION 



43 8 
440 
198 



ILBOSTPO 
ILBOSTPl 
ILB0FRR1 



ILBOSTPO 
ILBOSTPO 
ILBOERRO 



EA8 
FA6 



NAME LOCATION 



NAME LOCATION 



NAME LOCATION 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION 



43C 
EC 



ILBOOSPO 
ILBOEPRl 



ILBOOSPO 
ILBOERRO 



®( ENTRY AD 
\ TOTAL LE 

{£) ****RUN 



DRFSS 
NGTH 






DOFS NOT EXIST BUT HAS BEEN ADDED TO DATA SET 



®)lFF 
}lEF 

(iff 



IEF2 85I SYS71023.TO11209.RVOO0.TESTRUN.LOADSET 

2851 VOL SER NOS= 231401. 

2 851 SYS7102 3.TO11209.RVOO0.TFSTRUN.GODATA 

2851 VOL SER NOS= 00B116. 



DELETED 



Figure 53. Linkage Editor Output Showing Module Map and Cross-Reference List 



!• The jo b cont ro l statements . These 
statements are listed because 
MSGLEVEL=(1, 1) is specified on the JOB 
statement for this job, shown in 
Figure 52. 



2 • Al loc a tion m ess ages from the job 
scheduler . These messages provide 
information about the device 
allocation for the data sets in the 
job step. For example, the message 

IEF2371 230 ALLOCATED TO SYSUT1 



3 . Li nkage editor informative message . 
This message lists the PARM options 
that were specified. 



4 . Linkage editor informative me ssage. 
This is a disposition message 
describing the disposition of the load 
module. 



A. Name of the load module specified 
in the DSNAME parameter of the 
SYSLMOD DD statement 



indicates that the data set for SYSUT1 
has been assigned to the device 230. 



B. Text of message 
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5. Module map. The module map is listed 
when either the XREF or the MAP option 
is specified in linkage editor 
processing. The module map shows all 
control sections in the output module 
and all entry names in each control 
section. The control sections are 
arranged in ascending order according 
to tneir assigned origins. All entry 
frames are lisxeti below the exjrrtxol 
section in which they are defined. 
Each COBOL program is a control 
section, and any COBOL library 
subroutine is a separate control 
section (except as noted under 
segmentation) . 



A. Control sect ion . Under this 
heading the name, origin, and 
length of each control section is 
listed. 

Name . The name of the control 
section. This name is the 
PROGRAM-ID name in the main COBOL 
program or a called program. Each 
control section that is obtained 
from a library by an automatic 
liorary call is indicated by an 
asterisk. 

Origin . The relative origin in 
hexadecimal notation. 
Length . The number of bytes in 
each control section in 
hexadecimal notation. 



B. Entry . The entry names within 
each control section and their 
relative location. A called 
program may have more than one 
entry point. For a called COBOL 
program, the entry points are the 
same as the names specified by the 
ENTRY statements in the source 
program. 

C. Entry ad d ress . The relative 
address of the instruction with 
which processing of the module 
begins. It will always be INIT1 
if the COBOL program is the main 
program of the load module. 

D. Total length. The total number of 
bytes, in hexadecimal notation, of 
the load module. It is the sum of 
the lengths of all control 
sections. 



A. Location . The relative location 
in the program where another 
program is called. 

B. Symbol reference. Ihe name of the 
entry point of the called program. 

c » In control section . The control 
section that contains the entry 
■puiirt. 

For example, 440 is the location where 
a COBOL subroutine is called. 
ILBOSRV1 is the entry point of the 
called program. ILBOSRV0 is the 
control section that contains the 
entry point ILBOSTP1. 

If XREF is specified, the cross 
reference list appears before the 
Entry Address. 



7 . Disposition messages from the job 
scheduler . These messages contain 
information about the disposition of 
the data sets. 



Comments on the Module Map and Cros s 
Reference List 



The severity of linkage editor 
diagnostic messages may affect the 
production of the module map and the cross 
reference list. 

Since various processing options will 
affect the structure of the load module, 
the text of the module map and cross 
reference list will sometimes provide 
additional information. For example, the 
load module may have an overlay structure. 
In this case, a module map will be listed 
for each segment in the overlay structure. 
The cross reference list is the same as 
that previously discussed, except that 
segment numbers also are listed to indicate 
the segment in which each symbol appears. 

List i ng the Linkage Editor Control 
Statements : If the LIST option is 
specified, linkage editor control 
statements, such as OVERLAY and LIBRARY, 
are listed. 



6* Cross reference list . The cross 

reference list, as well as a module 
map, is listed if the XREF option is 
specified. The MAP and XREF options 
should not be specified together. The 
cross reference list provides the 
following information: 



Linkage Editor Messages 



The linkage editor may generate 
informative or diagnostic messages. A 
complete list of these messages is included 
in the publication IBM OS Linkage Editor 
and Loader. 
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LOADER OUTPUT 



• Debugging information 



Loader output consists of a collection 
of diagnostic and error messages, and, if 
MAP is specified, a storage map of the 
loaded program. The output data set, 
SYSLOUT is sequential and blocked as 
specified by the user in the DCB. For 
better performance, the user can also 
specify the number of buffers to be 
allocated. 

Diagnostic messages include a loader 
heading and a list of options requested by 
the user. The error messages, identifying 
the source of error, will be written when 
the error is detected. After processing is 
complete, an explanation of the error will 
be written. A complete list of loader 
diagnostic messages is found in the 
publication IBM OS Linkag e Edit or and 
Loade r. 

The map includes the name and absolute 
address for each control section and entry 
point defined in the program. It is 
written on SYSLOUT concurrently with input 
processing so it appears in order of input 
ESD items. The total size and storage 
extent also are included. Figure 54 is an 
example of a module map. 



COBO L LOAD MODULE EXECUTION OUTPUT 

The output generated by program 
execution (in addition to data written in 
program output files) can include: 

• Data displayed on the console, or on 
the printer 

• Cards 

• Messages to the operator 

• System informative messages 

• System diagnostic message 

• A system dump 



Note : If a program ends abnormally and 
one of the options FLOW, STATE, or SYMDMP 
is in effect and the SYSDBOUT DD card has 
been included, debugging information 
appears in the program listing (see the 
chapter entitled "Symbolic Debugging 
Features") . 

A dump as well as system diagnostic 
messages are generated automatically if a 
program contains errors that cause abnormal 
termination. 



Note: If a COBOL program abnormally 
terminates, then a formatted dump is 
provided for all COBOL programs compiled 
with the SYMDMP option which could include 
the abnormally terminating program and its 
callers, up to and including the main 
program. For a discussion of the SYMDMP 
option as well as of other COBOL symbolic 
debugging options, see the chapter entitled 
"Symbolic Debugging Features. " 

Figure 55 shows an example of output 
from the execution job step. The following 
text is an explanation of the illustration. 

1. The job control st atements . These 
statements are listed because 
MSGLEVEL=(1, 1) is specified in the JOB 
statement for this job. 

2 « Th§_l2^_§ll2cation_mess ages _f r om_t he 
job scheduler . These messages indi- 
cate the device that is allocated for 
each data set defined for the job 
step. 

3 . Di sposi t ion_messages _f r om_the_ job 
scheduler . These messages are 
contained in the publication IBM OS 
Mess ages and Codes . 

4. Pr ogram output on printer . The 
results of execution of the TRACE and 
EXHIBIT NAMED statements appear on 
program listing. 

5. Console output. Data is printed on 
console as a result of execution of 
DISPLAY UPON CONSOLE. 
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OS/360 LOADER 



OPTIONS USED - PRINT,MAP,NOLET,CALL,NORES,SIZE==424176 



NAME 


TYPE 


ADDR 


NAME 


TYPE 


ADDR 


NAME 


TYPE 


ADDR 


NAME 


TYPE 


ADDR 


NAME 


TYPE 


ADDR 


SAMPL2B 


SD 


161E0 


SAMPL2BA 


SD 


16EC8 


IHEMAIN 


SD 


17CF8 


IHENTRY 


SD 


17D00 


IHESPRT 


SD 


17D10 


SYSIN 


SD 


17D48 


IHEVQC i 


* SD 


17D80 


IHEVQCA * 


* LR 


17D80 


IHEVQB ' 


* SD 


17FD8 


IHEVQBA 


* LR 


17FD8 


IHEDIA < 


* SD 


183C0 


IHEDIAA i 


* LR 


183C0 


IHEDIAB * 


* LR 


183C2 


IHEVPE * 


► SD 


18608 


IHEVPEA 


♦ LR 


18608 


IHEVPA < 


> SD 


18870 


IHEVPAA * 


* LR 


18870 


IHEVFC < 


* SD 


189D0 


IHEVFCA i 


► LR 


189D0 


IHEVPC 


• SD 


189F8 


IHEVPCA * 


► LR 


189F8 


IHEVFE * 


► SD 


18BE8 


IHEVFEA ' 


► LR 


18BE8 


IHEVSC 


► SD 


18C08 


IHEVSCA 


♦ r.R 


18C08 


IHEDNC ' 


' SD 


18CB8 


IHEDNCA < 


» LR 


18CB8 


IHEDOA < 


► SD 


18F30 


IHEDOAA 


* LR 


18F30 


IHEDOAB 


* LR 


18F32 


IHEDMA < 


► SD 


19010 


IHEDMAA * 


* LR 


19010 


IHEVFD < 


> SD 


19108 


IHEVFDA * 


* LR 


19108 


IHEVFA 


* SD 


19160 


IHEVFAA * 


► LR 


19160 


IHEVPB * 


* SD 


19248 


IHEVPBA * 


* LR 


19248 


IHEXIS 


* SD 


193F0 


IHEXISO 


* LR 


193F0 


IHEIOB < 


* SD 


19488 
1A9C8 


IHEIOBA 
IHESADD ' 


> LR 
* LR 


19488 
1A9DE 


IHEIOBB_„< 
IHESAFF * 


>__LR_- 
* LR 


19490_ 
1AA18 


..... THETQBC--' 

IHEPRT < 


► SD 


- -1-9498- 
1AB70 


IHEPRTA 


♦ LR 


-^-Mftfr 


IHESARC * 


► LR 


1AB70 


IHEBEGA * 


" LR 


1AE28 


IHEERR * 


* SD 


1AE68 


IHEERRD < 


» LR 


1AE68 


IHEERRC ' 


* LR 


1AE72 


IHEERRB 


* LR 


1AB7C 


IHEERRA * 


* LR 


1AE86 


IHEERRE < 


> LR 


1B4E2 


IHEIOF < 


* SD 


1B580 


IHEIOFB ' 


* LR 


1B580 


IHEIOFA 


♦ LR 


1BS82 


IHEITAZ * 


" LR 


1B81E 


IHEITAX < 


* LR 


1B82A 


IHEITAA < 


► LR 


1B83E 


IHEDCN ■ 


► SD 


1B860 


IHEDCNA 


♦ LR 


1B860 


IHEDCNB < 


* LR 


1B862 


IHEIOD < 


* SD 


1BA50 


IHEIODG * 


* LR 


1BA50 


IHEIODP ' 


* LR 


1BAS2 


IHEIODT 


♦ LR 


1BBM 


IHEVTB * 


* SD 


1BCF0 


IHEVTBA * 


► LR 


1BCF0 


IHEVQA * 


► SD 


1BD78 


IHEVQAA 


* LR 


1BD78 









IHEQINV PR 


00 


IHEQERR 


PR 


SYSIN 


PR 


14 


IHEQLSA 


PR 


IHEQLW3 PR 


28 


IHEQLW4 


PR 


IHEQFVD PR 


3C 


IHEQCFL 


PR 


IHEQEVT PR 


58 


IHEQSLA 


PR 


IHEQSFC PR 


70 






IEW1001 


IHEUPBA 








IEW1001 


IHEUPAA 








IEW1001 


IHETERA 








IEW1001 


IHEM91C 








IEW1001 


IHEM91B 








IEW1001 


IHEM91A 








IEW1001 


IHEDDOD 








IEW1001 


IHEVPFA 








IEW1001 


IHEVPDA 








IEW1001 


IHEDBNA 








IEW1001 


IHEVSFA 








IEW1001 


IHEVSBA 








IEW1001 


IHEVCAA 








IEW1001 


IHEVSAA 








IEW1001 


IHEDNBA 








IEW1001 


IHEUPBB 








IEW1001 


IHEUPAB 








IEW1001 


IHEVSEB 








TOTAL 


LENGTH 


5068 






ENTRY 


ADDRESS 


17D00 







4 SAMPL2BB PR 

1 8 IHEQLW0 

2C IHEQLWE 

40 IHEQFOP 

60 IHEQSAR 



PR 


8 


SAMPL2BC 


PR 


C 


PR 


1C 


IHEQLW1 


PR 


20 


PR 


30 


IHEQLCA 


PR 


34 


PR 


48 


IHEQADC 


PR 


»C 


PR 


64 


IHEQLWF 


PR 


68 



IHEQSPR PR 1 

IHEQLW2 PR 24 

IHEQVDA PR 38 

IHEQXLV PR 50 

IHEQRTC PR 6C 



IEW1001 WARNING - UNRESOLVED EXTERNAL REFERENCE (NOCALL SPECIFIED} 

Figure 54. Module Map Format Example 



184 



© 
® 



XXGO EXEC PGM=*.LKED.SYSLMOD,COND=((5,LT,COB) f (5,LT,LKED>J 

XXSYSUDUMP DD SYSOUT=A 

//GO.SYSOUT OD SYSOUT=G 

//GO. SAMPLE DD UNlT=24nO,LABEL= ( t NL» 



IEF236I ALLOC. FOR TESTRUN GO 

IEF2371 242 ALLOCATED TO PGM=*.DD 

tEF237t 230 ALLOCATED TO SYSUDUMP 

IEF237I 230 ALLOCATED TO SYSOUT 

IEF237I 182 ALLOCATED TO SAMPLE 



00000210 
00000220 



® 



IEF285I SYS71023.T0U209.RV000.TESTRUN.GODATA PASSED 

FEF285I VOL SER NOS = DDB116. 

IFF285I SYS71023.T011209.SVOCO.TESTRUN.R0000011 DELETED 

IEF285I VOL SFR NOS= 231*00. 

IEF285I SYS7l023.T011209.SV00").TFSTRUN.R009OO12 SYSOUT 

IEF285I VOL SER NOS= 231400. 

1EF285I SVS71023.T011209.RVOO0.TESTRUN.RO000O13 DELETED 

'* IEF285I VOL SER NOS= L00300. 



58 
62 
66 
68 
62 
66 
62 
66 



(Repeat 21 times) 



© 



62 
66 
62 
66 
71 
74 
75 

WORK-RECORO = A 0001 NYC Z 

74 

75 

WORK-RECORD = B 0002 NYC I 

74 

75 

WORK-RECORD = C 0003 NYC 2 

74 

75" 

WORK-RECORD = D 0004 NYC 3 

74 

75 



WORK-RECORD = V 002? NYC 1 

74 

75 

WORK-RFCORD = W 0023 NYC 2 

74 

75 

WORK-RECORD = X 0024 NYC 3 

74 

75 

WORK-RECORD = Y 0025 NYC 4 

74 

75 

WORK-RECORD = Z 0026 NYC Z 

74 

78 



© 



A 0001 NYC 

B 0002 NYC 1 

P 0003 NYC ■> 

0004 NYC 3 



00 22 NYC 1 

0023 NYC 2 

0024 NYC 3 



Figure 55. Execution Job Step Output 
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REQUESTS FOR OUTPUT 



1. The programmer can request data to be 
displayed by using the DISPLAY 
statement and including the following 

■in fho -i<-»h prmtrnl 



can be found in the publication IBM OS F ull 
American Nationa l Standard COBOL. Version 4 
Messages. MCS considerations are discussed 
there also. 



//SYSOUT 



DD SYSOUT=A 



SYSTEM OUTPUT 



2. Message to the operator can also be 
displayed on the console when 
requested in the source program 
(DISPLAY UPON CONSOLE). 

3. The programmer can request debugging 
information in case of an abnormal 
termination by specifying FLOW and/or 
STATE and including the following in 
the job control procedure: 

//SYSDBOUT DD SYSOUT=A 



Informative and diagnostic messages may 
appear in the listing during execution of 
any job step. Further information about 
system diagnostics is found in the 
publication IBM_OS_Mes sages _and_Codes. 
COBOL messages and associated documentation 
for this compiler appear in the Program 
Product publication IBM_OS_Full_American 

Nat ional Standard COBOL, Version <4 

Messag es. 



4. The programmer can request a full 
dump, in case his program is 
terminated abnormally, by including 
the following in the job control 
procedure: 

//SYSABEND DD SYSOUT=A 

Note : Under MVT, the SPACE parameter 
should also be included in the DD 
statement. For example: 

//SYSABEND DD SYSOUT=A, X 

// SPACE= X 

// (125, (200,1000), RLSE) 



Dumps and debugging facilities are 
explained in "Program Checkout. " 



OPERATOR MESSAGES 



The COBOL load module may issue operator 
messages. A complete list of these 
messages and required operator responses 



Each of these messages contains an 
identification code in the first three 
columns of the message to indicate the 
portion of the operating system that 
generated the message. Table 23 lists 
these codes, along with an identification 
of each. 



Table 23. 




System Message Identification 
Codes 

Identification 



An on-line console 

the supervisor. 
An on-line console 
data management. 
A message from the 
A message from the 
A message from the 
A message from the 
A message from the 
A message from the 
data management. 



message from 

message from 

job scheduler. 
COBOL compiler. 
Sort program, 
assembler, 
linkage editor, 
supervisor and 
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PROGRAM CHECKOUT 



A programmer using the COBOL compiler 
under the IBM Operating System has several 
methods available to him for testing and 
debugging his programs or revising them for 
increased efficiency of operation. 

The syntax-checking options can be 
specified to save programmer and macuine 
time while checking the source statements 
for syntax errors. 

The COBOL debugging language can be used 
by itself or in conjunction with other 
COBOL statements. A dump can also be used 
for program checkout. For a discussion of 
the COBOL symbolic debugging options, see 
the chapter entitled "Symbolic Debugging 
Features. " 



Program debugging statements may not be 
desired after testing is completed. A 
debugging packet can be removed after 
testing. This allows elimination of the 
extra object program coding generated for 
the debugging statements. 

mU« /s^4.vv4ii. »■* v *-v ^2 * ■* « ^v -3 Wr* ±- 1*% ^ mr.Tv^TP — «■. J 

J.1J.C Ou/CpUL. piuum,ca uy uuc mnofi ai.iQ 

EXHIBIT statements is listed on the system 
logical output device (SYSOUT). If these 
statements are used, the SYSOUT DD 
statement must be specified in the 
execution time job step. 

The following discussions describe ways 
to use the debugging language. 



FOLLOWING THE FLOW OF CONTROL 



SYNTAX-CHECKING COMPILATION 



The compiler checks the source text for 
syntax errors and then generates the 
appropriate error messages. With the 
syntax-checking feature, the programmer can 
reguest a compilation either conditionally, 
with object code produced only if no 
messages or just W- or C-level messages are 
generated, or unconditionally, with no 
object code produced regardless of message 
level. 

Selected test cases run with the 
syntax-checking feature have resulted in a 
compilation-time saving of as much as 70%. 
For a discussion of the syntax-checking 
options, SYNTAX and CSYNTAX, see the 
section "Options for the Compiler" under 
"Job Control Procedures. " 



The READY TRACE statement causes the 
compiler generated card numbers for each 
section and paragraph name to be listed on 
the system output unit when control passes 
to that point. The output appears as a 
list of card numbers. 

To reduce execution time, a trace can be 
stopped with a RESET TRACE statement. The 
READY TRACE/RESET TRACE combination is 
helpful in examining a particular area of 
the program. The READY TRACE statement can 
be coded so that the trace begins before 
control passes to that area. The RESET 
TRACE statement can be coded so that the 
trace stops when the program has passed the 
area. The two trace statements can be used 
together where the flow of control is 
difficult to determine, e.g., with a series 
of PERFORM statements or with nested 
conditionals. 



DEBUGGING LANGUAGE 



The COBOL debugging language is designed 
to aid the COBOL programmer in producing an 
error-free program in the shortest possible 
time. The sections that follow discuss the 
use of the debugging language and other 
methods of program checkout. 

The three debugging language statements 
are TRACE, EXHIBIT, and ON. Any one of 
these statements can be used as often as 
necessary. They can be interspersed 
throughout a COBOL source program, or they 
can be in a packet in the input stream to 
the compiler. 



Another way to control the amount of 
tracing, so that it is done conditionally, 
is to use the ON statement with the TRACE 
statement. When the COBOL compiler 
encounters an ON statement, it sets up a 
mechanism such as a counter that is 
incremented during execution whenever 
control passes through the ON statement. 
For example, if an error occurs when a 
specific record is processed, the ON 
statement can be used to isolate the 
problem record. The statement should be 
placed where control passes only once for 
each record that is read. When the 
contents of the counter equal the number of 
the record (as specified in the ON 
statement) , a trace can be taken on that 
record. The following example shows a way 
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in which the processing of the 200th record 
could be selected for a TRACE statement. 



Col. 
1 



8 



Col. 

1 



DEBUG 



RD-REC. 
PARA-NM-1. 



ON 200 READY TRACE. 
ON 201 RESET TRACE. 



GROSS- PAY- CALC. 

COMPUTE GROSS-PAY = 
RATE- PER- HOUR * (HRSWKD 
+ 1.5 * OVERTIMEHRS). 

NET-PAY-CALC. 



If the TRACE statement were used without 
the ON statement, the processing of every 
record would be traced. 

A common program error could be either 

(1) failing to break a loop, or 

(2) unintentionally creating a loop. If 
many iterations of the loop are required 
before it can be determined that there is a 
program error, the ON statement can be used 
to initiate a trace only after the expected 
number of iterations has been completed. 

Note : If an error occurs in an ON 
statement, the diagnostic message may refer 
to the previous statement number. 



DEBUG NET-PAY-CALC 

SAMPLE- 1. ON 10 AND 

EVERY 10 EXHIBIT NAMED 
RATE- PER- HOUR, HRSWKD, 
OVERTIMEHRS, GROSS-PAY. 

This coding will cause the values of the 
four fields to be listed for every tenth 
data record before net pay calculations are 
made. The output could appear as: 



RATE-PER-HOUR = 4.00 HRSWKD = 40.0 

OVERTIMEHRS =0.0 GROSS-PAY = 160.00 



DISPLAYING DATA VALUES DURING EXECUTION 



RATE-PER-HOUR = 4.10 HRSWKD = 40.0 

OVERTIMEHRS =1.5 GROSS-PAY = 173.23 



A programmer can display the value of a 
data item during program execution by using 
the EXHIBIT statement. The three forms of 
this statement display (1) the names and 
values of the identifiers or nonnumeric 
literals listed in the EXHIBIT statement 
(EXHIBIT NAMED) whenever the statement is 
encountered during execution, (2) the 
values of the items listed in this 
statement only if the value has changed 
since the last execution (EXHIBIT CHANGED) , 
and (3) the names and values of the items 
listed in the statement only if the values 
have changed since the previous execution 
(EXHIBIT CHANGED NAMED). 

Note : The combined total length of all 
items displayed with EXHIBIT CHANGED and 
EXHIBIT CHANGED NAMED cannot exceed 32,767 
bytes. The length of any one operand must 
be less than or equal to 256 bytes. The 
length of a "NAME" must be less than or 
equal to 120 characters. 



RATE-PER-HOUR = 3.35 HRSWKD = 40.0 

OVERTIMEHRS =0.0 GROSS-PAY = 134.00 



Note : Decimal points are included in this 
example for clarity, but actual printouts 
depend on the data description in the 
program. 



The preceding is an example of checking 
at regular intervals (every tenth record) . 
A check of any unusual conditions can be 
made by using various combinations of COBOL 
statements in the debug packet. For 
example: 



IF OVERTIMEHRS GREATER THAN 2. 
EXHIBIT NAMED PAYRCDHRS 



Data can be used to check the accuracy 
of the program. For example, the 
programmer can display specified fields 
from records, work the calculations 
himself, and compare his calculations with 
the output from his program. The coding 
for a payroll problem could be: 



In connection with the previous example, 
this statement could cause the entire pay 
record to be displayed whenever an unusual 
condition (overtime exceeding two hours) is 
encountered. 



The EXHIBIT CHANGED statement also can 
be used to monitor conditions that do not 
occur at regular intervals. The values of 
the items are listed only if the value has 
changed since the last execution of the 
statement. For example, suppose the 
program calculates postage rates to various 
cities. The flow of the program might be 
as shown in Figure 56. 



01 



02 



03 



01 


10 


02 


15 


03 




04 


10 


01 




02 


20 


03 


15 


04 




01 


10 



1 



\ READ INPUT 
\ DATA FOR / < 
\ CITY 



— 



The first column contains the code for a 
state, the second column contains the code 
for a city, and the third column contains 
the code for the postage rate. The value 
of an item is listed only if it is changed 
since the previous execution. For example, 
since the postage rate to city 02 and 03 in 
state 01 are the same, the rate is not 
printed for city 03. 



| CALCULATE | 
| RATE FOR | 
| CITY j 
L T J 



r t 

| EXHIBIT | 
| CHANGED | 
L ^ J 



The EXHIBIT CHANGED NAMED statement 
lists the name of the data item and the 
value of that item if the value has 
changed. For example, the program might 
calculate the cost of various methods of 
shipping to different cities. After the 
calculations are made, the following 
statement could be in the program: 



EXHIBIT CHANGED NAMED STATE CITY RAIL 
BUS TRUCK AIR 



V 



v^LAST^V NO ^-^ 

\>city/^ v_y 



YES 



The output from this statement could appear 
as: 



STATE = 01 CITY = 01 RAIL = 10 
BUS = 14 TRUCK = 12 AIR = 20 



CITY = 02 



L . J 

Figure 56. Example of Program Flow 



CITY = 03 BUS = 06 AIR = 15 

CITY = 04 RAIL = 30 BUS = 25 
TRUCK =28 AIR =34 



The EXHIBIT CHANGED statement in the 
program could be: 



STATE = 02 CITY = 01 TRUCK = 25 
CITY = 02 TRUCK = 20 AIR = 30 



EXHIBIT CHANGED STATE CITY RATE 



The output from the EXHIBIT CHANGED 
statement could appear as: 



Note that the name of the item and its 
value are listed only if the value has 
changed since the previous execution. 
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TESTING A PROGRAM SELECTIVELY 



A debug packet allows the programmer to 
select a portion of the program for 
testing. The packet can include test data 
and can specify operations the programmer 
wants performed. When the testing is 
completed, the p acket ca n be remov ed. The 
flow of control can be selectively altered 
py the inclusion of debug packets, as shown 
in Figure 57. 



START 



r 

1 


DEBUG | 


1 

1 


PACKET J 

FOR A | 

J 



I 

I 
, J 



| DEBUG | 
| PACKET j 
| FOR C | 
L T J 



| STOP | 
| RUN | 

L J 



Figure 57. Selective Testing of B 



In this program, A creates data, B 
processes it, and C prints it. The debug 
packet for A simulates test data. It is 
first in tne program to be executed. In 
the packet, the last statement is GO TO B, 



which permits A to be bypassed. After B is 
executed with the test data, control passes 
to the debug packet for C, which contains a 
GO TO statement that transfers control to 
the end of the program, bypassing C. 



TESTING CHANGES AND ADDITIONS TO PROGRAMS 



If a program runs correctly but changes 
or additions can make it more efficient, a 
debug packet can be used to test changes 
without modifying the original source 
program. 

If the changes to be incorporated are in 
the middle of a paragraph, the entire 
paragraph, with the changes included, must 
be written in the debug packet. The last 
statement in the packet should be a GO TO 
statement that transfers control to the 
next procedure to be executed. 

There are usually several ways to 
perform an operation. Alternative methods 
can be tested by putting them in debug 
packets. 

The source program library facility can 
be used for program checkout by placing a 
source program in a library (see 
"Libraries"). Changes or additions to the 
program can be tested by using the BASIS 
card and any number of INSERT and DELETE 
cards. Such changes or additions remain in 
effect only for the duration of the run. 

A debug packet can also be used in 
conjunction with the BASIS card to debug a 
program or to test deletions or additions 
to it. The debug packet is inserted in the 
input stream immediately following the 
BASIS card and any INSERT or DELETE cards. 



DUMPS 



If a serious error occurs during 
execution of a program, the job is 
abnormally terminated; any remaining steps 
are bypassed, and a dump is generated. The 
programmer can use the dump for program 
checkout. (However, any pending transfers 
to an external device may not be completed. 
For example, if a READY TRACE statement is 
in effect when the job is abnormally 
terminated, the last card number may not 
appear on the external device. ) In cases 
where the abnormal termination does not go 
to completion, a dump is not produced. 
This situation may cause duplicate name 
definition when the next job is run, and is 
discussed at the end of this section. 
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include 

the system will provide the progr ammer with 

a ,~£ji£tou^^ 

format, of main storajg^ Those areas 

occupied i,L "^*'^1fe'''profelem program and its 

data at the time the error occurred, will 

be included. This printout is called an 

abnormal termination dump and is identified 

by the heading 

*** ABDUMP REQUESTED *** 

I f a SYSABEND DP statemen t.„J^L»apfeolf led , 

printed. 

If neither a SYSUDUMP nor a SYSABEND DD 
statement is included in the execution-time 
job step, or its specification has been 
destroyed, an indicative dump is produced. 
This dump does not contain a printout of 
main storage and is not given under MVT. 

All dumps include a completion code 
designating the condition that caused the 
termination. The completion code consists 
of a system code and a user code- Only one 
of the codes is nonzero. A nonzero system 
code indicates that the control program 
detected the error. 

The COBOL programmer can now request 
dynamic dumps via a compile-time option. 
The SYMDMP option, requested in the PARM 
parameter of the EXEC statement, produces a 
symbolic formatted dump of the data area of 
the object program when the program 
abnormally terminates. At execution time, 
the user can also request a dynamic dump at 
any point in the Procedure Division. 

Notes : 



abnormally terminated and a dump to be 
listed. 



Input/Outp ut Errors 



Errors can occur while a COBOL file is 
being processed. For example, during data 
transmission, an input/output error may 
occur that cannot be corrected. If the 
file being processed is organized 
sequentially and no error-processing 
declarative or INVALID KEY option has been 
specified for the file, the job is 
terminated. If it is a QSAM file, the job 
will be terminated when there is no 
declarative or INVALID KEY option and the 
EROPT=ABE option in the DD statement has 
been specified. 

Referring to an input area before OPEN 
and READ statements are issued can cause 
unpredictable results, because base locator 
(BL> cells and registers are not properly 
initialized. 

Another error that can cause termination 
is an attempt to read a file whose records 
are of a different size than those 
described in the source program. The 
section "Additional File Processing 
Information" contains more information 
about input/output errors. 



Errors C aused by Invalid Da ta 



Abnormal termination of a job occurs 
when a data item with an invalid format is 
processed in the Procedure Division. 



If a COBOL program abnormally 
terminates, then a formatted dump is 
produced for all COBOL programs 
compiled with the SYMDMP option which 
could include the abnormally 
terminating program and its callers, up 
to and including the main program. 

The explanation of the system-generated 
completion codes and a complete 
description of the dumps are contained 
in the publication IBM OS P rogram mer's 
Guide to Debu gging. For a discussion 
of the COBOL symbolic debugging 
options, see the chapter entitled 
"Symbolic Debugging Features." 



ERRORS THAT CAN CAUSE A DUMP 



Some of the program errors are: 

1. A data item in the Working-Storage 
Section is not initialized before it 
is used, causing invalid data to be 
picked up. 

2. For an item whose usage is 
COMPUTATIONAL, C0MPUTATI0NAL-1, Or 
C0MPUTATI0NAL-2, either the alignment 
is incorrect, or the description of 
the item does not specify the proper 
alignment. Some examples are: 

a. A redefining entry contains one or 
more of the above items and the 
redefined entry is not properly 
aligned. Alignment will not be 
performed for items that cause the 
starting address of the redefining 
item to be changed. 



Following is a discussion of some error 
conditions that can cause a program to be 



b. A record in the Linkage Section of 
a called program is described by 
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an 01 entry and contains one or 
more of the above items, and the 
corresponding argument in the 
calling program is not properly 
aligned. 

c. A file, containiny one or more of 
the above items, is blocked, but 

the regui red inter- record slack 

bytes were not inserted when the 
file was created. If the file is 
later read as an input file, the 
alignment may not be correct. 



An input file or received message 
contains invalid data or data 
incorrectly defined by its data 
description. For example, the 
contents of the sign position of an 
internal or external decimal data item 
in the file may be invalid. The 
compiler does not generate a test to 
check the sign position for a valid 
configuration before the item is used 
as an operand. 



The data description in the Linkage 
Section of a called program does not 
correctly describe the data defined in 
the calling program. 



i->XGUino l.^.uu xuuv ^wv.i 



>1^o ^c-F- 



as numeric generate an invalid sign. 



11. Some common errors that occur when 

clearing group items in storage are: 

a. Moving ALL ZEROS to a group level 
item to clear several counters 
causes an invalid sign to be 
generated in all of the elementary 
fields except the lowest order 
field. 

b. Moving SPACES to a group level 
item will put invalid data in any 
numeric field in that group. 

c. Moving to a group level item 
moves one zero and pads the rest 
of the fields with blanks. 



If a group item is moved to a group 
item and the subordinate data 
descriptions are incompatible, the new 12. 
data in the receiving field may not 
match the corresponding data 
descriptions. (Conversion or editing 
is not performed in a move involving a 
group item. ) 



The SIZE ERROR option is not specified 
for the COMPUTE statement and the 
result of the calculation is larger 
than the specified resultant 
COMPUTATIONAL data name. Using the 
result in a subsequent calculation 
might cause an error. 

The SIZE ERROR option is not specified 
for a DIVIDE statement, and an attempt 
is made to divide by zero. 13. 

The USAGE specified for a redefining 

data item is different from the USAGE 

specified for the redefined item. An 

error results when the item is 

referred to by the wrong name for the 14. 

current content. 

A record containing a data item 
described by an OCCURS clause with the 
DEPENDING ON dat a-name option, may 
cause data items in the record to be 
affected by a change in the value of 
data-name during the course of program 
execution. This may result in 
incorrectly described data. 
Additional information about how to 
correct this situation is included in 
"Programming Techniques." 



Failure to initialize counters 
produces incorrect results. No 
initial values are generated by the 
compiler unless specifically 
instructed to do so with a VALUE 
clause. If such fields are defined as 
decimal, internal or external, invalid 
signs may result in addition to 
unpredictable initial values. If 
defined as binary, they will cause 
unpredictable results and, further, if 
used in subscripting, may exceed the 
range of the associated OCCURS clause 
and cause data to be fetched or stored 
erroneously. An addressing exception 
may occur if the uninitialized 
subscript generates a bad address. 

Not testing to insure that a subscript 
or index does not exceed the range of 
the associated OCCURS clause may lead 
to fetching and storing data from and 
to some incorrect locations. 

Failure to initialize an index 
produces incorrect results. No 
initial values are generated by the 
compiler unless a SET statement is 
executed. When indexing is then 
specified, the range of the OCCURS 
clause may be exceeded and cause data 
to be fetched or stored erroneously. 
An addressing exception may occur if 
the initialized index generates an 
address outside the range of the 
machine, or a protection exception if 
data is stored outside the partition 
of this program. 
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15. A subscript or index set at zero will 
address data outside the range of the 
table. 



16. If either HIGH-VALUE or LOW-VALUE is 
moved to internal or external decimal 
fields and those fields are used for 
comparisons, computations, or 
subscripting, a data exception will 
occur. HIGH-VALUE and LOW-VALUE are 
the hexadecimal values X'FF' and 
X* 00' , respectively. 



Other Errors 



1. No DD statement is included for a file 
described in the source program and an 
attempt is made to access the file. 
When an OPEN statement for the file is 
executed, the system console message 
is written. The programmer can elect 
to direct the operator to continue 
processing his program, but any READ 
or WRITE associated with the unlocated 
file will result in an abnormal 
termination. A similar situation 
exists when a file is closed WITH LOCK 
and an attempt is made to reopen it 
(see the Program Product publication 
IBM OS Full American Nationa l Sta ndard 
COBOL, Version H Messages for the 
format of the generated error 
message) . 

2. A file is not opened and execution of 
a READ or WRITE statement for the file 
is attempted, or a MOVE to a record 
area in the file is attempted. 

3. A GO TO statement, with no procedure 
name following it, is not properly 
initialized with an ALTER statement 
before the first execution of the GO 
TO statement. 



4. Reference is made to an item in a file 
after end of data. This includes the 
use of the TERMINATE statement of the 
Report Writer feature, if the CONTROL 
FOOTING, PAGE FOOTING, or REPORT 
FOOTING contain items that are in the 
file (e.g., SOURCE data-name, where 
data-name refers to an item in the 
file). 



7. A READ is issued for a data set 
referenced on a DD DUMMY statement. 
The AT END condition is sensed 
immediately and any reference to a 
record in the data set produces 
unpredictable results. 

8. Under MVT, a STOP RUN statement is 
executed before all files are closed. 

9. A SORT did not execute successfully. 
The programmer may check SORT-RETURN. 

10. An input/output statement is issued 
for a file after the AT END branch is 
taken, without closing and reopening 
the file. 

11. A SEND or RECEIVE statement is issued 
when a message control program is not 
running. 

12. A SEND or RECEIVE statement is issued 
for a QNAME (i.e., the "QNAME=" 
parameter of the DD card) that is 
unknown to the message control 
program. 



In. addition to errors that can result in 
an abnormal termination, errors in the 
source program can occur that cause parts 
of the program to be overlaid and the 
corresponding object code instructions to 
become invalid. If an attempt is then made 
to execute one of these instructions, an 
abnormal termination may result because the 
operation code of the instruction is 
invalid, the instruction results in a 
branch to an area containing invalid 
instructions, or the instruction results in 
a branch to an area outside the program, 
such as an address protected area. 



Some COBOL source program errors that 
can cause this overlaying are: 

1. Using a subscript whose value exceeds 
the maximum specified in the 
associated OCCURS clause. 

2. Using a data-name as a counter whose 
value exceeds the maximum value valid 
for that counter. 



COMPLETION CODES 



5. Block size for an F-format file is not 
an integral multiple of the record 
length. 

6. In a blocked and/or double buffered 
file, a count cannot be kept directly 
in a record. 



The following cases represent some of 
the errors that can occur in a COBOL 
program and the interrupt or completion 
code associated with them. These errors do 
not necessarily cause an abnormal 
termination at the time they are recognized 
and do not always hold true. 
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1. 013 — Check register 2 of registers at 

the entry to ABEND. This address 
points to the DCB in conflict. 

2. 043 — Error occurred during the 

attempted opening of a TCAM 
application program data set, as 
described below. 



c. 



found in register 1. This should 
point to the DD name of a missing 
DD statement. 

When the interrupt is at 00004A, 
look for a missing card, i.e., 

//SYSOUT DD SYSOUT=A 



a. A value _.of. 0A..An__re.g.i.ste.r__0_ _. 

indicates the attempted opening of 
a TCAM application program data 
set without an active message 
control program (MCP) in the 
system. 

b. A value of 02 indicates that the 
QNAME= parameter of a DD statement 
associated with an input or output 
DCB for a COBOL program is not the 
name of a process entry defined in 
the terminal table. 

c. A value of 03 indicates that the 
process entry named by the QNAME= 
parameter of a DD statement 
associated with a COBOL program is 
currently being used by another 
COBOL program. 

d. A value of 04 indicates that 
insufficient main storage was 
available in the MCP to build 
internal control blocks associated 
with the COBOL program interface. 
Specify a larger region or 
partition size in the JOB 
statement for the MCP. 



d. 



anv rtiisgjnn ,T C !.._. cg-T^ 
name of a JCL card. Add 
hexadecimal 28 to the address 
found in register 1 at entry to 
ABEND. This should point to the 
DD name of the DD statement in 
error. 

When interrupt is at 00004F, look 
for inconsistent JCL or check the 
system-name in the COBOL program. 



5. 0C4 — Protection Exception: 

a. Check for the block size and 
record size being equal for 
variable record input or output. 

b. Check for missing SELECT 
statement. 

c. If interrupt is at 004814, check 
for an attempt to READ an unopened 
input file or a missing DD card. 

d. Check for an uninitialized index 
or subscript. 



e. A value of 05 indicates that 
insufficient main storage was 
available in the COBOL work area 
to build internal control blocks. 
Specify a larger region or 
partition size in the JOB 
statement for the COBOL program. 

046 — Error occurred during the 

termination of the TCAM MCP 
because the COBOL program data 
set was still open. Specify the 
STOP RUN statement when COBOL 
processing is complete. Ensure 
that all COBOL programs have 
terminated processing before 
deactivating the MCP. 



0C1 — Operation Exception: 

a. When the interrupt is at 000048 or 
at 004800, look for a missing DD 
card or an unopened file. 

b. When the interrupt is at 000050, 
look at register 1 of the 
registers at entry to ABEND. Add 
hexadecimal 28 to the address 



6. 0C5 and 0C6 — Addressing and 

Specification Exception: 



a. 



b. 



c. 



d. 



e. 



f. 



Subscript or index value may have 
exceeded maximum and instruction 
or table area was overlaid. 

Check for an improper exit from a 
procedure being operated on by a 
PERFORM statement. 

Check for duplicate close of an 
input or output file if DS 
formatting discontinued. 

A sort is being attempted with an 
incorrect catalog procedure. 

Attempting to reference an 
input/output area before a READ or 
OPEN statement, respectively. 

Alignment for COMPUTATIONAL data 
is incorrect when record is 
blocked, and inter-record slack 
bytes were not inserted. 

Check for initialized subscript or 
index value. 
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7. 0C7 — Data Exception: 

a. Data field was not initialized. 

b. Input record numeric field 
contains blanks. 

c. Subscript or index value exceeded 
maximum and invalid data was 
referenced. 

d. Data was moved from the DISPLAY 
field to the COMPUTATIONAL or 
COMPUTATIONAL- 3 field at group 
level. Therefore, no conversion 
was provided. 

e. The figurative constants ZERO or 
LOW-VALUE moved to a group level 
numeric field. 

f. Omission of USAGE clause or 
erroneous USAGE clause. 

g. Incorrect Linkage Section data 
definition, passing parameters in 
wrong order, omission or inclusion 
of a parameter, failure to carry 
over a USAGE clause when 
necessary, or defining the length 
of a parameter incorrectly. 



001— I/O Error: 

a. Register 1 of the SVRB points to 
the DCB which caused the 
input/output problem. Look for 
input record and blocking errors. 
That is, the input does not agree 
with the record and blocking 
descriptions in the DCB, the COBOL 
file description, or the DD 
statement LRECL parameter. 

b. Attempted to READ after EOF has 
been sensed. 



9. 002 — Register 2 of registers at the 
entry to ABEND contains the 
address of the DCB for the file 
causing the input/output problem. 
Check the DCB list for the 
specific file. 



10. 213 — Error during execution of OPEN 
statement for data set on mass 
storage device, as follows: 

a. DISP parameter of DD statement 
specified OLD for output data set. 

b. Input/output error cannot be 
corrected when reading or writing 
the DSCB. Recreate the data set 
or resubmit the job, check 



register 14 of the registers at 
entry to ABEND. This address 
points to the file that has no 
DSCB. 



11. 214 — Error during CLOSE for data set 

on tape; there is an input/output 
error that cannot be corrected 
either in tape positioning or 
volume disposition. Resubmit the 
job and inform the field engineer 
if error persists. 



12. 237 — Error at EOV: 

a. Incorrect volume serial number 
specified in SER subparameter of 
VOLUME parameter of DD statement. 

b. Incorrect volume jnounted. 

c. Incorrect labels. 



13. 400 — If this completion code is 

generated during a compile step, 
the member to be compiled has not 
been extracted from the source 
library for compilation* 



14. 413 — Error during execution of an OPEN 

statement for a data set on tape: 

a. Volume serial number was not 
specified for input data set. 

b. Volume could not be mounted on the 
allocated device. 

c. There is an input/output error in 
reading the volume label that 
cannot be corrected. 

15. 806 — The error occurred during 

execution of a LINK, XCTL, 
ATTACH, or LOAD macro 
instruction. An error was 
detected by the control program 
routine for the BLDL macro 
instruction. The contents of 
register 15 indicates the nature 
of the error: 

04 The reguested program was not 
found in the indicated source 
private, job, or link library. 

08 An uncorrectable input/output 
error occurred when the control 
program attempted to search the 
directory of the library 
indicated as containing the 
requested program. 
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16. 80A — Insufficient contiguous core 

storage for linkage to some phase 
of the compiler* The programmer 
should look to see if secondary 
data-set allocation has caused an 
extra DEB to be built at lower 
core addresses within the region. 
If so, this problem can be 
corrected by assigning sufficient 
.nrimarw. PvfpntR for the data set 



in question. 

Requirements' 

information. 



See "Data Set 
for further 



3. From Procedure Division map: 

a. Find the highest previous relative 
address in the condensed listing. 
That statement is in error. 

b. Get line number and verb of COBOL 
source statement. 



4. From source listing find the line 
number and verb of source statement 
causing program interruption. 



17. 813 — Error during execution of an OPEN 
statement in verification of 
labels: 



USING THE ABNORMAL TERMINATION DUMP 



a. Volume serial number specified in 
VOLUME parameter of DD statement 
is incorrect. 

b. Data set name specified in DSNAME 
parameter is incorrect. 

c. Wrong volume is mounted. 

18. When compilation is terminated with 
diagnostic message IKF0010I-D, 
IKF0020I-D, or IKF0030I-D, an abnormal 
termination dump is generated to 
provide additional debugging 
information. 



The programmer can also determine the 
cause of an abnormal termination with the 
following material : 



1. The COBOL program object code listing. 



2. A knowledge of the layout of the COBOL 
object module. 



3. The full abnormal termination dump in 
conjunction with the linkage editor 
map or cross reference list. 



Find inq Location of Program Inter ruption in 
COBOL Source Pro gram U sing the Co ndensed 
Listing 



To determine the location of the 
interruption, the programmer should proceed 
as follows: 



1. 



From first page of dump: 
a. 



b. 



Get completion code and program 
interruption storage location. 

Determine the starting address of 
the program (PRB address+20). 



2. From linkage editor listing: 

a. Determine storage address for each 
module. Add starting address of 
the program to origin of each 
module. 

b. Determine module in which 
interrupt storage location falls. 

c. Determine relative address. 
Subtract module storage address 
from interrupt location. 



A description of the linkage editor 
output and of the COBOL object code listing 
is found in "Output." Figure 53 shows the 
layout of the COBOL program object module. 



Note : The information in this section 
about the use of the abnormal termination 
dump applies only when running under MFT. 
For information about the abnormal 
termination dumps under MVT, see the 
publication IBM OS Programmer's Guide to 
Debugging. Note that under the MVT option 
no indicative dumps are given. 



The abnormal termination dump provides 
the address at which the load module has 
been loaded (load address) and the address 
of the instruction that caused the 
interrupt. The programmer computes the 
load module area by adding the load address 
to the load module length, as shown in the 
linkage editor output. It is now possible 
to determine whether the instruction falls 
within the load module. If it does not, 
the interrupt could have resulted from an 
improper branch to a point outside the load 
module or an error occurring in another 
part of the system. 
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If the instruction does fall within the 
load module, the programmer now determines 
in which part: the main program, a COBOL 
library subroutine, or a called program. 
The ranges of the various parts are 
determined by adding their relative 
origins, as shown in the linkage editor 
output, to the load address. 



If the instruction occurred in an object 
module generated for a COBOL program, 
(i.e., the main program), the programmer 
can determine whether or not the 
instruction was one of the generated object 
code instructions. He can determine the 
address of the first instruction in the , 
Procedure Division (as found in the object 
code listing) by adding its relative 
location to the location of the object 
module (load address plus relative origin). 
If it was one of the object code 
instructions, a similar technique can be 
used to locate the exact instruction. If 
it was not one of these instructions, the 
error has occurred in another part of the 
object module. Control possibly went there 
because of an improper branch. 



If the instruction that initiated the 
dump occurred in a COBOL library 
subroutine, or if the original program 
called another program and the instruction 
occurred in the called program, the 
instruction can be located by a similar 
technique. The linkage editor cross 
reference list indicates the locations 
where the call to the program or subroutine 
in question was made. 



The following general rules can be used 
to determine the cause of the dump and the 
error. 



1. Determine the COBOL statement that 
generated the code leading to the 
program check. 

a. The top of the system dump will 
tell the address of the PC 
(Program Check) instruction and 
the type of PC. Locate the 
instruction in the core dump= 

b. Determine the relocation factor of 
the program from the linkage 
editor map. Subtract the 
relocation factor from the address 
of the invalid instruction. 

c. The address that results may be 
located in the procedure division 
map generated by the MAP option. 
(The coding shown at this location 
of the map should correspond to 



the instruction located in step 
one. ) 

d. Preceding the address and code 
found in step three, find the 
sequence number of the 
corresponding COBOL statement in 
the listing and the number of the 
element in the sentence that 
generated the code. 



2. Be sure the COBOL statement is coded 
properly. 



3. If the statement is coded properly, go 
back to the core dump and determine 
the type of PC. 

a. If it is a data exception, the 
programmer will probably find that 
the instruction is a decimal 
instruction, and that one of the 
fields either will not have a 
valid sign or will contain digits 
other than to 9. To determine 
this, it will be necessary to find 
the fields in core storage. 
Inspect bits 4 through 7 of the 
low-order byte for a valid sign 

(A through F) . If one is not 
present* this is the cause of the 
PC. 

If one or both of the fields 
being operated on are defined as 
external decimal, the programmer 
will find one or more pack 
instructions immediately ahead of 
the PC instruction. From these 
determine the address of the 
external decimal field that 
generated the invalid sign. 
Several common causes of data 
exceptions are given in "Errors 
Caused by Invalid Data. " 

b. If it is a protection exception, 
one possible cause is that a base 
register used in the instruction 
has not been initialized. Base 
registers in COBOL are initialized 
at different times. For input 
files, the register is not 
initialized until the first 
successful read; it is not 
initialized when the file is 
opened. For output files, the 
registers are initialized during 
the processing of the OPEN 
statement. When faced with a 
protection exception, the 
programmer should go to the COBOL 
source program to ascertain that 
no data has been moved prior to 
the time when base registers are 
initialized. 
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c. If an addressing or specification 
exception occurs, the programmer 
may find upon inspection (but not 
always) that registers have been 
unexpectedly modified and the 
problem becomes one of finding out 
how. Two possible approaches are: 

(1) Check the addresses in 
registers 14„and 15 against 
the address of the PC 
instruction. If the address 
of the PC instruction is egual 
to or slightly larger than the 
address in register 15, the 
address probably is in a 
subroutine, and the address in 
register 14 should be the 
return address. A BAL or BALR 
instruction probably will 
precede the return address. 
The programmer should look for 
this particularly when the 
problem is not with a COBOL 
statement. If the PC 
instruction has an address 
equal to or a bit larger than 
the address in register 14, 
then the programmer probably 
has just returned from a 
subroutine, and register 15 
should still be pointing to 
the entry address of the 
subroutine. The programmer 
should check the coding to see 
if this could reasonably be 
so, and check the entry points 
listed on the linkage editor 
map. If this approach bears 
further action, a listing of 
the subroutine would be needed 
or the instructions from the 
dump must be interpreted. 

(2) If the foregoing step does not 
locate the error, the 
programmer should check back 
through the dump to see what 
exists between the PC 
instruction and the last 
unconditional branch in order 
to determine the possible 
course of events. 

The sample COBOL program ABEND and its 
output, shown in Figure 58 for a 
nonsegmented program and in Figure 59 for a 
segmented program, illustrates in detail 
the way in which an object code listing, a 
cross-reference table, and an abnormal 
termination dump can be used together to 



debug a program. The circled numerals in 
the figures are cited in the associated 
text. Note that all values are expressed 
in hexadecimal format unless otherwise 
indicated. 

In both examples of the ABEND program, 
the completion code in the dump, fl) , 
indicates the condition causing the 
abnormal t-e-r-rai-nat-i on* If the system part 
of the code is nonzero, the explanation can 
be found in the publication IBM OS 
Programm er's Guide to Debugging . In the 
program ABEND, the completion code is 0C7; 
invalid data is the reason for termination. 

Debu g ging a Nonsegmented Pr ogram : 
Suggested below are general procedures for 
locating and correcting the source 
statement responsible for abnormal 
termination. 

1. The PROGRAM INTERRUPTION (DATA) AT 
LOCATION hhhhhh entry, (2) , gives the 
hexadecimal address of the instruction 
following the instruction that 
initiated the interrupt and caused the 
dump. This address can be used to 
determine the relative location of the 
instruction in the load module (see 
item 4 below). In the example, the 
address is B52D0. 

2. To determine the main storage area 
occupied by the load module, add the 
total length of the module, in 
hexadecimal format, to its load 
address. The load address can be 
obtained from the USE/EP entry, (3), of 
the first ACTIVE RBS (Request Blocks) 
specification. The last six digits of 
this entry are the address of the 
entry point (INIT1) in the COBOL 
program. In this case, the address is 
B5020 in hexadecimal format. 

The total length of the load module 
is indicated in the TOTAL LENGTH 
entry, Q*Jf in the linkage editor 
output i3 40, in the example). The 
highest location in the load module 
is: 

B5020 + 540 = B5560 



Thus, the range is from B5020 to 
B5560. Since the address B52D0 falls 
within this range, the instruction 
initiating the dump must be within the 
load module. 
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O00O1 I n r- M T I F IC4TI IN DIVISION. 

10007 PU'r.RAM-ID. ABEND. 

00001 PFM^oi'S. 

O" 00 * THIS IS A PROGRAM TO ILLUSTRATE THE ABNORMAL 

Oil" TERMINATION OF A NONSEGMENTED PROGRAM. 

00006 ENVIRONMENT DIVISION. 

0000 7 CONFIGURATION SECTION. 

0010R SOURCE-COMPUTER. IBM-360-H50. 

10009 OBJECT-COMPUTER. IBM-360-H50. 

00011 DATA DIVISION. 
0001? 

00013 WORKING-STORAGE SFCTinN. 

00014 01 'ECORDA. 

00015 0? A PICTURE S"(4> VALUE 1234. — N 
0001ft 02 B PFOFFINPS A PICTURF S^fT) COMPUTATIONAL-3. (%} 
00017 "ROCEDUPE DIVISION. ^-^ 
00118 COMPUTF B = R ♦■ 1 . (^) 

10019 STOP RUN. V_/ 



TNTRNL NAME LVL SOU°CE NAME 
1NM=l-037 01 RECPRDA 

1NM=l-063 0? R 



MFMORY MAP 

TGT 000<50 

SAVE AREA 0009C 

SWITCH OOODS 

TALLY OOOOC 

SORT SAVE OOOEO 

FNTRY-SAVE 0OOF4 

SORT CORE SUE OOOFf> 

RFT mOF OOOEC 

SORT RFT OOOEE 

WORKING CFLL< OOOFO 

SORT FILF SI?F 0"2?0 

SORT MQOE SI7F 00224 

DGT-VN TBL 0C27S 

TGT-VN TRl 0C22C 

VCONPTR 00230 

LENGTH OF VN tbl 0O?34 

LAREl RFT 00716 

CURRENT PRJODTTY 00737 

UNUSED 00738 

INIT1 AOCON 00740 

DER'IG TABLF °TR 00744 

UNUSED 00748 

•-IVERFLOW CFLl S 1024C 

Rl CELLS 0^?4C 

OFCRADR CELLS 00250 

TEMP STORAGF 00250 

TFMP (JTO^AGC-? 00250 

TFMO STOSAGF-3 00250 

TFMP STORAGF-4 00750 

RLl CFLLS 00750 

VLC CFLLS 0O258 

SBL CFILS 00758 

INOEX CFLLS 00758 

SUSADP CELLS 00258 

ONCTL CELLS 0075» 

PPMCTl CFLLS 00758 

PFMSAV CELLS 00258 

VN CEILS 00?5« 

SAV C ARFA =2 10758 

SAVE ARFA =3 00258 

XSASH CELLS 01758 

XSA CELLS 00758 

PARAM CFl LS 00258 

RPTSAV ARFA 00258 

CHECKPT CT° 00758 

VCON TRL 0175« 



LITERAL POOl (HEX) 
00270 (LIT + O) 1C 



pr.T 00760 

OVERFLOW CEI ! S 00760 

VIPTUAL CELLS 00760 

OROCFDURF NAME CELLS 00768 

gir.jjin.TCn uiup CFLLS 00268 

OCR AODRFSS CFILS 0076C 

VNI CELLS 0076C 

LITFRAIS 00270 

0ISP1 AY L!TF°Al <: 0077] 



BASE 


r)ts°L 


INTRNL NAME 


DEFINITION 


USAGE 


BL = 1 


000 


DNMxl-032 


OS 0CL4 


GROUP 


8L = ! 


OQQ 


nNH=i-052 


OS 4C 


DISP-NM 


RL = 1 


000 


DNM=l-063 


OS 4P 


COMP-3 



Figure 51. Nonsegmented COBOL Program with /abnormal Termination Dump (Part 1 of 3) 
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, r r r<Ar,e c;t 


apts m i 


'irM 


rniM oroR'( rn" a 


1 FNGTH OF 1000 


a , 




compute 


ooi?T? 
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START 
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FOU 
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F A 
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00077H 
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OO077P 


SB 


FO C 104 




L 
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07 


FF 




B r .H 


15,15 






ooo? it- 


SO 
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S* 
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51 


SO 004 




SI 
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SO 


FO 1 0S4 




ST 
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Q4 
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Nt 
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SH 
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L 
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V F R = l 
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OS 
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SO 
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ST 
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12 
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LTP 
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07 
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96 
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SWT*0 
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OS 


F1 
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11 
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TM 
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SWT + O 
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47 
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bc 
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9R 
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LM 
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5R 
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1 
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S« 
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I 
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07 
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15,14 
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16 


71 1) 14« 




ru 
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41 


61 "04 




LA 
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41 
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L4 
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4 1 


71 r 010 
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0007CP 


06 


70 
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7,0 






0007CA 


IS 


SO 
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5,0 
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40 1 001 




L 
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OCO700 


IE 


4B 
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50 


40 1 010 




ST 


4,000(0,1 1 






000206 


R7 
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BXLE 


1,6,100(5) 






0002DA 


41 


10 11c 




14 


R,1BC(P,13) 


0VF=1 




"007DF 


41 


70 1RF 




LA 
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OS 
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0002E4 
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00 s 000 




L 
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IF 
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Si 
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ST 
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0002EE 


R7 
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BXIE 
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S3 
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L 
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5R 
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L 
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07 
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RCF 
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OO 
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STM 
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1R 
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LR 
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000006 


OS 


FO 




8 ALP 
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000008 


45 


30 F HO 
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oooooc. 


r. ic?r.snsr.440404i 




nc 


X« C1C7C5P5C4404 04 0' 






000014 


ciosf2C3 




or 


X«C1D5F2C3' 






oooiir 


07 


00 




RCO 


0,0 






000014 


93 


9F F 12<, 




LM 


9,15,0241 15) 






0000 IF 


07 


FF 




RCP 


15,15 






001070 


96 


07 1 014 




01 


034( I) ,X'02' 






00P0?4 


07 


FE 




RCP 


15,14 






100026 


41 


FO 001 




LA 


15,001(0,0) 






00002A 


07 


FF 




BCP 


15,14 






10002C 


00000740 




ADCON 


L4(!NIT3) 






10H31 


ooooooro 




ADCON 


L4( IN1T1) 






000014 


11010101 




AOCON 


L4IINTT1I 






0D013P 


00001761 




A0C1N 


L4IPGT) 






0H03C 


00110110 




AOCON 


L4(T0.T) 






000040 


O01O0777 




4DCIN 


L4ISTAPT) 






001044 


OOC0077F 




ADCON 


L4( INIT7I 






iooo4q 








os 
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♦STATISTICS* SOUPCF RECORDS = 19 U4TA DIVISION STATFMENTS = 3 PROCFDURF DIVISION STATEMFNTS = 

*O n TIONS IN FFFECT* SIZF = 319?0 RUF = 2768 LINECNT = S7 SPACE1, FLAGW, SEO, SOURCE 

♦OPTIONS IN EFFECT* 0"4P, PMAP, NOCLIST, NOS'IPMSP, NOXREF, NnSXRFF, LD4P , NOOECK, APOST, NOTRUNC, NT'FLOW 

♦OPTIONS IN EFFFCT* NOTERM, NON'JM, NOHATCH, NONAMF, COMPILE=01, NOSTATF, LIB, VERB, ZWB, SYST 



FRB-LFVFL LINKAGE EDITOR nPTIONS SPECIFIED XPF c , L I ST , LF T 

VARIABLE OPTIONS MSEO - S I ZF=( 9? 160 , 31 92 ) DEFAULT OPTION(S) USFD 

CROSS REFFRENCF TARLE 

CONTROl SECTION ENTRY 

NAM>- ORIGIN LENGTH NAMF LnCATIiN NAME LOCATION NAME LOCATION NAME LOCATION 



ABEND nr, 

TLBOSTPO* 300 







ILROSTPl 31C 



LOCATION RFFE'S TO SYMROL IN CONTROL SECTION LOCATION PFFFRS TO SYMBOL IN CONTROL SECTION 

?6i ILBOSTPO ILP.OSTPO ?*,4 UBOSTPl ILBOSTPO 



FNTRY A1QRESS 
TOTAL LENGTH 



340 

DO^S NOT EXIST BUT HAS BEEN AOOFD TO DATA SET 



Figure 58. Nonsegmented COBOL Program with Abnormal Termination Dump (Part 2 of 3) 
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♦ Acnicp rfoutsuo * 
jrm aiumo ?TFr> no 

cn^PirrinN rnriF systfm ^ octQ) 

PROGHA" INTrP ll«>Tt'lN (DAT*) AT LOCATION 014?9? 

INTFOOl|t>T AT 01*798 Q) 

PSW AJ F^TRY Tn ARENO <"F]c,innn O014298 



TTMF 013907 I1ATF 710"7 



tcb 0053ns 



rr ooo6CO«n 

mss oooi546 r ' 

fsa 1806Cfro 

use oooooonn 



"if ooooonoo 

P^/FI.G 1091040R 

tcr oooooooo 



OFB P006CDP4 

Fir, oocoo2fr 

TMF 00005488 



T IDT P306CFIP 

its oooooooo 
pin foooqfco 



r.np 80oc7ooo 

JLB 00010000 
NSTAF 00000000 



TPN 00000000 
JSF OOOOOOOO 
TCT 000001TC 



ACTIVE RRS 

PP.B 014003 NM RUN 



S7/STAR 006C00Cn USE/FP 00»1'4320 PSH FF15000D C0014298 000000 MT/LNK 0000530* 



SV*B P6C0FP NM SVC-401C S7/STAR 0012017? USE/FP 10004IA8 PSW FF040033 40004370 EB03E8 WT/LNK 00014000 
RG 0-T P00140AR 50014304 00060000 00060000 00014020 500142EC 0001 40* R 000I426F 
RG 8-15 00014770 000142CO 00014020 00014020 00014280 000140BO 000142<»2" 500142C2 



SVRR 06C080 NH SVC-105A S7/STAI1 0O0CO17? 
RG 0-7 00014360 000143R8 
RG 8-15 0000545E 0001442E 



USF/FP 000041A8 PSW FF041230 R000043C C803C8 WT/INK 0006C0E0 
0H001?n 400041AA 00000000 POOOOOPO 00014360 R000435F 
00060000 ^0005308 0000530R 000143CR 600043FA 0001429? 



P/P STORAGE BOUNDARIES 00014000 TO 00060000 

FREF AOEAS SIZF 

014668 000582A8 
06C050 00000030 
06CEF8 00000028 

SAVE AREA TRACE 

RUN MAS ENTFRED 



06CFB0 W01 03000000 
Rl 0006CFFR 
R7 0006CC30 

0140BO WD1 00000000 
PI 00000000 
R7 00000000 



HSA 00000000 
R2 00060000 
R8 0006CF78 

HSA 0006CFR0 
R? 00000000 
°R 00000000 



LSA 000140BO 

R3 00060000 

R9 00000000 

LSA 08000026 

R3 80000000 

"9 00000001 



PFT 000064CC 
R4 0006CF70 
RIO 0006CFB0 

RET 00000001 
R4 00000000 
RIO 00004000 



EPA 50014020 
R5 00000060 
»ll 0006CFF8 

EPA 00000001 
R5 00000000 
"11 00000001 



RO 00000068 
R6 00005308 
R12 600143EA 

RO 00000000 
R6 00000000 
R12 42000001 



REGS AT FNTRY TO ABEND 

FL.PT.RFGS 0-6 00.000000 00000000 



REGS 0-7 
REGS 8-15 



000140A8 
00014270 



50014304 
00P142C0 



00.000000 00000000 



00.000000 00000000 



00.000300 00000000 



0006DOO0 
00014020 



00060000 
00014020 



00014020 
00014280 



500142EC 
000140B0 



000140A8 
00014292 



0001426F 
500142C2 



P/P STORAGE 

014000 09E40540 40404040 006COOC0 00014020 

014020 90ECD00C 185D05F0 45ROF010 C1C2C505 

014040 96021034 07FE41F0 000107FE 000142CO 

014060 00014292 0001429F OOOOOOOO 00000000 

014080 OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

0140A0 OOOOOOOO OOOOOOOO F1F2F3C4 OOOOOOOO 

0140CO 00000001 OOOOOOOO OOOOOOOO OOOOOOOO 



FF153000 C0014298 OOOOOOOO 00005308 

C4404040 C1D5E2C3 0700989F F02407FF 

00014020 00014020 00014280 000140BO 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

OOOOOOOO OOOOOOOO OOOOOOOO OOOOOOOO 

OOOOOOOO 0006CFB0 08000026 00000001 

80000000 OOOOOOOO OOOOOOOO OOOOOOOO 



♦ RUN 

*.......0..0. ABEND 

* 



0* 

ANSC....0...* 
... ....... .* 



,1230 * 



Figure 58. Nonsegmented COBOL Program with Abnormal Termination Dump (Part 3 of 3) 
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3. To determine the relative location 
within the load module of the 
instruction indicated in the 
INTERRUPTION entry, subtract the load 
address from the address of the 
instruction. In the example, this 
becomes • 

B52D0 - B5020 = 2B0 

4. To determine whether or not the 
instruction occurred in the object 
module generated for the program, 
compare its relative location (2B0) 
with the total length, Q*J* of the 
object module. If the relative 
location were greater than the size of 
the object module, then the error 
would not be part of this program. A. 
relative location between the size of 
the program, \$) t and the total length 
would indicate that the abnormal 
termination had occurred in one of the 
COBOL library subroutines. Such an 
error could be located by comparing 
the relative location with the 
relative origin of the subroutines. 

In this example, 2B0 is less than the 
program size (356), so the instruction 
occurred in the main program. 

5. To determine whether or not the 
abnormal termination occurred in one 
of the object code instructions 
generated as a result of a statement 
in the Procedure Division of the 
source program, compare its relative 
location with the relative location of 
the first generated instruction in the 
Procedure Division, Q>J- In this 
example, the relative location of the 
instruction is greater than that of 
the first generated instruction 

(2B0 > 2AA) and so it can be found by 
locating the corresponding relative 
location. The immediately preceding 
object code instruction then is the 
instruction that initiated the dump, 
{Jj* In this example, it is an 
instruction generated as a result of a 
COMPUTE statement. Checking back to 
the source program listings the 
corresponding statement, (jp , is 



located and ' B' is seen to be the 
data-name that caused the trouble. 
Data item^^is defined in the Data 
Division, {9J, as a COMPUTATIONAL- 3 or 
internal decimal item, but the value 
at B is there as a result of a VALUE 
clause for A. the item that B 
redefines. This value is in external 
decimal format since there is no USAGE 
clause specified. The configuration 
of A is invalid for B and results in 
an interrupt. 

Determining the Location of an ABEND When 
Running Dy namically: When running 
dynamically, the programmer should do the 
following to determine whether the abend 
occurred in the main program. 

1. The compiler produces a Load List that 
contains the COBOL subroutine library 
names and the addresses used in the 
program. Thgse are anything beginning 
with ILBO. (lu Figure 59 is a Load 
List, the letters corresponding to the 
explanation in the text. The 
programmer is particularly interested 
in any ILBO subroutine that does not 
end in a zero, such as ILBORNT, 
ILBOREC, ILBODSP, etc. 

2. In this case, the abend has occurred 
at 441CC. To determine whether this 
is within the main program, go to the 
Load List, and look for the subroutine 
with its address closest to that of 
the abend. ILBOREC (b\ has an address 
of 043E18. ^-^ 

3. Look below to the second part of the 
Load List. This contains the length 
of the subroutines that begin at the 
address specified above. In this case 
at 043E18, under the LN column, ihe 
length of the subroutine is 9E8 (cj. 
Adding the length of the subroutine 
9E8 to the starting address 043E18, 
results in a number falling within the 
confines of the main program. 

4. After this is determined, the 
programmer continues his debugging in 
the specified manner. 
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C 
►1 
0) 



NE 000238A8 
NE 000?^388 
000246E3 
000?5368 



NF 



NE 00026108 



RSP-CDE 0itt)23n28 

PSP-CDE 01028708 

RSP-CDE 01073D20 

RSP-CDE 1028768 

RSP-CDE 01023F1O 

PSP-CDE 010248A8 



Nf 00023898 
Nf 00023R20 
NE 000244A8 
NE 0002495,0 
NE 000253A8 
NE 00000000 



RSP-CDf; 31028308 

PSP-CDE 010281DB 

RSP-CDE 01023DE8 

RSP-CDE 0102PTAO 

RSP-CDE 01P23E28 

R'Sp-CDF 01024968 



NE 000?38AO 
NF 000241B0 
NE 0002^5b0 
NF P0024R80 
NE 00P?^3C0 



RSP--COE 01028238 

RSP--CDF 010231338 

RSP--C0E 01028308 

PSP--CDF 01028338 

PSP-CDE 0107470R 



tr 1 
o 

ft) 
C/3 



02531)8 
023928 



AT Pi OB 
ATPl 3 



NCDE 000000 
NC^F 02 3A7 8 



ROC-RB 00025200 
ROC-RB 00000000 



NM PUN 

NM IGC0A05A 



USE Oi 
USE 0? 



E°A 041698 
FPA 40.9 60 



ATP 2 2 
ATP2 28 



XL/MJ 0253C8 
XL/MJ 023908 



028308 


ATR1 


30 


NCOE 


028333 


ROC 


028238 


ATRI 


BO 


NCDF. 


028268 


ROC 


028208 


AjRl 


RO 


NCOE 


28238 


RDC 


0281D8 


ATR1 


!3 


NCOE 


028208 


ROC 


023 833 


AT PI 


31 


NCOE 


2 3D2 


ROC 


02-3020 


ATRI 


31 


NCOE 


2 3Df-8- 


HOC 


023DF8 


ATRI 


33 


NCDE 


023F10 


ROC 


028308 


ATF1 


RO 


NCOE 


2833 8 


ROC 


07a2F>8 


AT?T 


°0 


NCOF 


028298 


ROC 


0281A8 


ATR 1 


RO 


NCOE 


2 8 ] D 8 


ROC 


028338 


Atri 


BO 


NCDF 


2 836 


ROC 


0*3ElO 


ATttl 


0-3 


NCOE 


0241B8 


ROC 


023E28 


ATPl 


37 


NCOE 


024870 


ROC 


0241R8 


ATRI 


33 


NCDE 


023E28 


ROC 


0247X8 


atri 


37 


NCDF 


07 48C0 


ROC 


024870 


ATPl 


3 3 


NCDE 


24 7C8 


ROC 


0248A8 


ATkl 


37 


NCDE 


C24R88 


ROC 


024 SCO 


ATRt 


13 


NCDE 


02-48A8- 


•HOC 


024963 


ATPl 


16 


NCOE 


02 530 8 


ROC 


024B88 


ATRI 


12 


NCOE 


024968 


ROC 



-RB 00000000 
-Rfl 00000000 
-■RB 00000000 
-RB 00000000 
-PR 00000000 
-«B 00000000 
-RB 00000000 
-RR 00000000 
-RB 00000000 
-RB 00000000 
-PB 00000000 
-ft 8 00000000 
-RB 000241 oo 
-PR 00000000 
-R<3 00024100 
-PB 00000000 
-RB 000241 no 
-RB 00000000 
-RR 000241D0 
-RB 00000000 



LN 



















PAGE 0002 


NM 


1GG019CD 


USE 


02 


FPA 


07F130 


A T R2 


?0 


XL/MJ 


0282F8 


NM 


IGG019CJ 


USE 


02 


EPA 


070D10 


ATP? 


?o 


XI /MJ 


028228 


NM 


IGR019BA 


«SF 


02 


EPA 


07DRP0 


ATP? 


?0 


XL/MJ 


0?81 F8 


NM 


IGG019RB 


USE 


02 


EPA 


07OA58 


ATP2 


20 


XL/MJ 


0781C8 


NM 


IGG019RL 


USE 


01 


ERA 


040B48 


AT "2 


?0 


XL/MJ 


023R28 


NM 


IGG019RG 


USE 


01 


EPA 


040C90 


ATR? 


?o 


XL/MJ 


023010 


NM 


URORNT 


USF 


01 


FPA 


041088 


ATP2 


20 


XL/MJ 


0230E8 


NM 


IGG019CD 


USE 


0? 


EPA 


07F130 


ATR2 


?o 


XL/MJ 


0282F3 


NM 


TGG019CT 


USE 


02 


EPA 


07E020 


AT"? 


20 


XL/MJ 


028258 


NM 


IGG019AI 


USE 


02 


EPA 


070908 


ATP? 


?o 


XL/MJ 


028198 


fyjM 


IGr,0l9A D 


USE 


02 


EPA 


07E3A0 


ATR? 


20 


XL/MJ 


028328 


NM 


IL8OSRV0 


USE 


01 


EPA 


04145A 


ATR2 


?0 


XL/MJ 


0246A8 


NM 


ILBOPFCO 


USF 


00 


EPA 


043E1A 


AT p 2 
ATR2 
ATP 2 


10 

20 
10 


XL/MJ 
XL/MJ 
XL/MJ 


0241B8 
024798 
074870 


NM 


HlborEc 


USE 


01 


FPA 


043E18I 


MM 


ILRODSPO 


4 USE 


"0 


FPA 


043062 


NM 


ILRnOSP 


USF 


01 


FPA 


043060 


ATP? 


?0 


XL/MJ 


0?47R8 


NM 


ILRON T RO | 


USE 


00 


FPA 


042872 


A T P2 


10 


XI /MJ 


0248C0 


NM 


ILB0NT« / 


USF 


01 


EPA 


04287? 


ATP2 


20 


XL/MJ 


024898 


NM 


ILBOCOMO / 


use 


0^ 


EPA 


041 508 


ATP? 


10 


XL/MJ 


024R88 


NM 


ILHOCOM / 


USE 


01 


EPA 


0415D8 


ATP2 


20 


XL/MJ 


024DR0 



— ® 



AOP 






nj 
o 

3 

n 

D" 

ft) 
o 
?r 
o 
c 
ft 



0253C8 
023908 
0282T8 
028228 
0281E8 

o 2tH.es 

023B28 
023D10 
023DEF 
0282F8 
02825H 
028196 
02832)? 
0246A6 
a?:479-3 
02473 p 
024898 
0240BO 



02 3'-)4 
02 39 6 
023980 
0239A0 
'J239T0 



SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 000OO01G 

SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 000 coo 10 

SZ 00000010 

SZ 00000010 

SZ 00000010 

SZ 0000001C 

SZ 00000010 

SZ 000C0010 

SZ 00000010 



NO 0000000 1 
NO 0000000 1 
NO 0000000 1 
NO 00000001 
NO ^00000^1 
NO 0000000 I 
NO 00000001 
NO 0000000 1 

nc oooonooi 

NO 0000000 1. 
NO OOOPOCKH 
NO 0000000 1 
NO 00000001 
NO 00000001 
NO C0000001 
Nf! 00000T0 1 
NO 0C000001 
NO 00000001 



00P00P.9/+ 00000B94 

00000306 00002BE0 11000000 04023E68 

1R000000 EF04F2A0 04023948 1000296C 

OOOCOOOO 00000000 00000070 C2C2C2C1 

OOOCOCCO O'OOOnooO OOOPOOOO H30n0065 



80001168 
800006AO 
80000270 
800001 10 

eooooi90 

80000178 
60000148 
80000870 
8O0O03D0 
80000270 
80000110 
80000080 
80C00100 
B0O0Q180 



t80C009F8^ 



800007A0 
80000790 
800000CO 



00041698 
0004C960 
O007E130 
0007DP10 
Qno7 0B«0 
00O7OA53 
0004 DB48 
00040C9C 
0004 1088 
0007E130 
0007F-02P 
0007 D908 
0007 F 3 i\0 
00041458 



00P43E1 



00 043060 
00042870 
000415D8 



3~© 



C.0000R04 oo^7nr)io o^oooR94 ooc n oooo 

100230C8 83000000 8E000O00 01000000 

OOOOOOlO O'OOOOOl^ 00090032 00010001 

C3DIC3C4 00000000 00000000 00000000 



.BRRACJCD * 

, R301C * 



Otfft 
023DA0 



OOOOOCOO OOOOOoor 



Debuggin g a Segmen ted Program : Below are 
the recommended steps for identifying the 
segment executing at the time of the error 
causing abnormal termination. 



5. 



1. 



2. 



3. 



The PROGRAM INTERRUPTION (DATA) AT 

u v, i« u u u «_j iW\ 

11111111111.1 c:ui_i 



T *"*/"■ 7V UlTPil 



hexadecimal address of the instruction 
following the instruction that 
initiated the interrupt and caused the 
dump. This address can be used to 
determine the relative location of the 
instruction in the load module (see 
item 3 below). In the example (Figure 
60), the address is 14BCE. 

To determine the main storage load 
address of the load module, subtract 
the length of the segment table 
($SEGTAB) from the entry point 
address. The load address can be 
obtained from the USE/EP entry, ^3J, of 
the first active RBS (Request Blocks) 
specification. The last six digits of 
this entry are the address of the en- 
try point (INITD in the COBOL 
program. In this case, the address is 
14050. 

©The length of the segment table, 
, in the linkage editor output is 20 
in this example. The load address of 
the module is : 

14050 - 20 = 14030. 

To determine the relative location of 
the instruction indicated in the 
INTERRUPTION entry, subtract the load 
address from the address of the 
instruction. In the example, this 
becomes: 



6. 



7. 



Subtract the starting address of the 
transient area from the relative 
location of the abnormally terminating 
instruction, as below: 



B9E - B88 



16 



Therefore, 16 is the relative address 
of the instruction immediately 
following the one responsible for the 
abnormal termination. It remains to 
identify the segment of the program in 
which this instruction occurs. 

To find location 16 in the segment 
being executed at the time of the 
abnormal termination, compute the sum 
of the location of CURSEGM, (Y\, and 
the load address (computed in item 3). 

14030 + B29 = 14B59 

The hexadecimal contents of the byte 
indicated, (&), identify this segment. 
In this example, the hexadecimal value 
is 32 (which is equivalent to the 
decimal value 50), so the priority 
number of the current segment is 50. 

In the section of priority 50 (SEC50), 
the instruction immediately following 
the one that caused the^abnormal 
termination is a Load, (9J , so that the 
instruction causing the data interrupt 
was the Add Decimal instruction at 
location 10. In this example, as in 
the nonsegmented program ABEND (Figure 
58), this instruction was generated as 
the result of a COMPUTE statement. 



14BCE - 14030 = B9E. 

4. To determine whether or not the 

abnormal termination occurred in the 
object module generated for the 
program, compare its relative location 
(B66) with the starting address of 
each cf the modules following $SEGTAB. 
The last of these modules ($ENTAB) 
begins at B70 and ends at B87. 
Because the location B9E is beyond the 
range of locations in the main program 
and the COBOL subroutines, the 
instruction initiating the dump would 
appear to be in another program. 
However, another check must be made. 
If the location B9E is less than the 
TOTAL LENGTH, @, but greater than the 
end of^SENTAB, it is in the transient 
area, ("6J . 



Findin g Data Records in an Abnormal 
Termination Dump 



The glossary, listed when the DMAP 
option is specified, contains information 
about all data-names described in the COBOL 
source program. The location assigned to a 
given data-name may be found by using the 
BL number and displacement specified for 
that entry in the glossary, and then 
locating the appropriate BL cell in the 
TGT. The hexadecimal sum of the glossary 
displacement and the contents of the cell 
should give the relative address of the 
area desired. This can be converted to an 
absolute address as described in the text 
associated with Figure 59 (for a 
nonsegmented program) and Figure 60 (for a 
segmented program) . 
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00002 
OOO0J 

oooou 

0000'j 
OOOOfa 
00007 
00008 
00009 
00010 
00011 
00012 
00013 

00014 

00015 
00016 
00017 
00018 
00019 
00020 
00021 
00022 
00023 
00024 



IDENTIFICATION DIVISION. 

PROGRAM-ID. ABEND. 

REMARKS. 

THIS IS A PROGRAM TO ILLUSTRATE THE ABNORMAL 
TERMINATION OF A SEGMENTED PROGRAM. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-360-H50. 

OBJECT-COMPUTER. IBM-360-H50. 

DATA DIVISION. 

WORKING-STORAGE SECTION 
01 RECORD A 

02 A PICTURE S9(4) VALUE 1234. 

02 B REDEFINES A PICTURE S9(7) COMPUTATIONAL-3. 
PROCEDURE DIVISION. 
SEC10 SECTION 10. 

DISPLAY ' START TEST' . 
BEGIN. 

READY TRACE. 
SEC50 SECTION 50. 

COMPUTE B = B + 1. 

STOP RUN. 



INTRNL NAME LVL SOURCE NAME 

DN.4=l-080 01 RECORDA 

DN>i=l-100 02 A 

DNM=1-111 02 B 



BASE DISPL INTRNL NAME DEFINITION US&GE 

BL=1 000 DNM=l-080 DS 0CL4 GROUP 

BL=1 000 DNM=1-100 DS 4C DISP-NM 

BL=1 000 DNM=1-111 DS UP COMP-3 



MEMORY MAP 




TGT 


00090 


SAVE AREA 


00090 


SWITCH 


000D8 


TALLY 


000DC 


SORT SAVE 


0OOE0 


ENTRY-SAVE 


000E4 


SORT CORE SIZE 


000E8 


RET CODE 


000EC 


SORT RET 


OOOEE 


WORKING CELLS 


000F0 


SORT FILE SIZE 


00220 


SORT MODE SIZE 


00224 


PGT-VN TBL 


00228 


TGT-VN TBL 


0022C 


VCONPTR 


00230 


LENGTH OF VN TBL 


00234 


LABEL RET 


00236 


CURRENT PRIORITY 


00237 


UNUSED 


00238 


INIT1 ADCON 


00240 


DEBUG TABLE PTR 


00244 


UNUSED 


00248 


OVERFLOW CELLS 


0024C 


BL CELLS 


0024C 


DECBADR CELLS 


00250 


TEMP STORAGE 


00250 


TEMP STORAGE- 2 


00250 


TEMP STORAGE- 3 


00250 


TEMP STORAGE- 4 


00250 


BLL CELLS 


00250 


VLC CELLS 


00258 


SBL CELLS 


00258 


INDEX CELLS 


00258 


SUBADR CELLS 


00258 


ONCTL CELLS 


00258 


PFMCTL CELLS 


00258 


PFMSAV CELLS 


00258 


VN CELLS 


00258 


SAVE AREA =2 


00258 


SAVE AREA =3 


00258 


XSASW CELLS 


00258 


XSA CELLS 


00258 


PARAM CELLS 


00258 


RPTSAV AREA 


00258 


CHECKPT CTR 


00258 


VCON TBL 


00258 



PGT 

OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
DCB ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERALS 



00268 
00268 

0027C 
00280 
00280 
00280 
00281 



Figure 60. Segmented COBOL Program with Abnormal Termination Dump (Part 1 of t) 
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. ASSIGNMENT 

BL =1 
T0RA3E STARTS AT LOCATION 00086 FOR A LENGTH OF 00008. 



SEGMENT OF PTY 50 



000000 




000000 


58 FO C 004 


000001 


05 IF 


000006 


000140 


000009 


05F2F240404040 


nnnoin 


fa 1(1 h nnn r 01? 


00001b 




000016 


58 FO C 00C 


00001A 


07 FF 




_ _ 



'® 



15,004(0,1 

1,15 

X' 000140' 

X'O5F2F240 



15, OOC<0,] 
15,15 



VdLBODSPOl 



V(ILBOSTPl) 



ROOT SEGMENT 



LITERAL POOL (HEX) 
00280 (LIT+0) J 



DISPLAY LITERALS (BCD) 
00281 (LTL+1) 'START TEST' 



00028C 










00028C 


58 


FO 


C 


004 


000290 


05 


IF 






000292 


00014C 


) 




000295 


05F1F840404040 


00029C 


58 


FO 


C 


004 


0002AO 


05 


IF 






0002A2 


0001 






0002A4 


10 








0002A5 


00000A 




0002A8 


0C000013 


1 


0002AC 


0000 






0002AE 


FFFF 






0002BO 


58 


FO 


c 


004 


0002B4 


05 


IF 






0002B6 


000140 




0002B9 


05F2F040404040 


0002C0 


96 


40 


D 


048 


0002C4 


58 


00 


C 


010 


0002C8 


13 


00 






0002CA 


58 


FO 


c 


008 


0002CE 


05 


EF 






0002D0 


50 


DO 


5 


008 


0002D4 


50 


50 


D 


004 


0002De 


50 


EO 


D 


054 


0002DC 


94 


EF 


D 


048 


0002EO 


58 


FO 


C 


000 


0002E4 


05 


EF 






0002E6 


50 


10 


D 


1B8 


0002EA 


12 


00 






0002EC 


07 


89 






0002EE 


96 


10 





048 


0002F2 


05 


FO 






0002F4 


91 


20 


D 


048 


0002F8 


47 


SO 


F 


016 


0002FC 


98 


2D 


B 


050 


000300 


58 


00 


B 


048 


000304 


58 


EO 


D 


054 


000308 


07 


FE 






00033A 


87 


16 


5 


000 


00033E 


41 


80 


D 


1BC 


000342 


41 


70 


D 


1BF 


000346 


05 


10 






000348 


58 


00 


8 


000 


00034C 


IE 


OB 






00034E 


50 


00 


8 


000 


000352 


87 


86 


1 


000 


000356 


58 


60 


D 


1BC 


00035A 


58 


EO 


D 


054 


00035E 


07 


FE 






000000 


90 


EC 


D 


ooc 


000004 


18 


5D 






000006 


05 


FO 






000008 


45 


80 


F 


010 


00000C 


ci: 


:2C5D5C440404 


000014 


C1D5E2C: 


1 


000018 


07 


00 






00001A 


98 


9F 


F 


024 


00001E 


07 


FF 






000020 


96 


02 


1 


034 


000024 


07 


FE 






000026 


41 


FO 





001 


00002A 


07 


FE 






00002C 


000002F2 




000030 


oooooooo 




000034 


00000000 




000038 


00000268 




00003C 


00000090 




000040 


0000023C 




000044 


000002D0 




000048 











L 


15,004(0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X" 000140' 




DC 


X' 05F1F840404040* 




L 


15,004(0,12) 


V(ILBODSPO) 


BALR 


1. 15 




DC 


X'0001' 




DC 


X'lO 1 




DC 


X' 0OO00A' 




DC 


x'ocooooig 1 


LIT+1 


DC 


x'oooo 1 




DC 


X'FFFF' 




L 


15,004(0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X' 000140' 




DC 


X'05F2F040404040' 




01 


048(13), X' 40' 


SrtT+0 


L 


0,010(0,12) 


PN=01 


LCR 


0,0 




L 


15,008(0,12) 


V(ILBOSGMO) 


BALR 


14,15 




ST 


13,008(0, 5) 




ST 


5,004(0, 13) 




ST 


14,054(0,13) 




NI 


048(13), X' EF' 


SHT+0 


L 


15,000(0,12) 


VIR=1 


BALR 


14,15 




ST 


1,188(0,13) 




LIR 


0, 




BCR 


8,9 




01 


048(13), X' 10' 


SHT+0 


BALR 


15,0 




TM 


048(13), X' 20' 


SWT+0 


BC 


14,016(0,15) 




LH 


2,13,050(11) 




L 


0,048(0, 11) 




L 


14,054(0, 13) 




BCR 


15,14 




BXLE 


1,6, 000(5) 




LA 


8,1BC(0, 13) 


OVF=l 


LA 


7,1BF(0, 13) 


TS=01-1 


BALR 


1,0 




L 


0,000(0, 8) 




ALR 


0,11 




ST 


0,000(0, 8) 




BXLE 


8,6, 000(1) 




L 


6,1BC(0, 13) 


BL =1 


L 


14,054(0,13) 




BCR 


15, 14 




STM 


14, 12, 00C(13) 




LR 


5,13 




BALR 


15,0 




BAL 


8,010(0, 15) 




DC 


X' C1C2C5D5C4404040' 




DC 


X'C1D5E2C3' 




BCR 


0,0 




LM 


9, 15, 024(15) 




BCR 


15,15 




01 


034(1), X'02' 




BCR 


15,14 




LA 


15,001(0, 0) 




BCR 


15,14 




ADCON 


L4(INIT3) 




ADCON 


L4(3EGMT) 




ADCON 


L4QNIT1) 




ADCON 


L4(PGT) 




ADCON 


L4(TGT) 




ADCON 


L4( START) 




ADCON 


L4(INIT2) 




Do 


15F 





Figure 60. Segmented COBOL Program with Abnormal Termination Dump (Part 2 of 4) 
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♦STATISTICS* SOURCE RECORDS = 24 DATA DIVISION STATEMENTS = 3 PROCEDURE DIVISION STATEMENTS = 

♦OPTIONS IN EFFECT* SIZE = 81920 BUF = 2768 LINECNT = 57 SPACE1, FLAGW, SEQ, SOURCE 

+OPTIONS IN EFFECT* DMAP, PMAP. NOCLIST, NOSUPMAP, NOXREF, NOSXREF, LOAD, NODECK, APOST, NOTRUNC, NOFLOW 

| *OPTIONS IN EFFECT* NOTERM, NONUM, NOBATCH, NONAME, COMPILE=01, NOSTATE, LIB, VERB, ZWB, SYST 



F88-LEVEL LINKA3E EDITOR OPTIONS SPECIFIED LIST, LET, XREF, OVLY 
VARIABLE OPTIONS USED - SIZE=< 92160, 8192) 
IEW0000 INSERT ABEND 
IEWOOO0 OVERLAY A 
It!WO000 INSERT ABEND50 
IttfOOOO ENTRY ABEND 



DEFAULT OPTION(S) USED 



CROSS REFERENCE TABLE 



CONTROL SECTION 

NAME ORIGIN LENGTH SEG. NO. 

$SEGTf^B 00 20 1 (A/ 

ABEND 20 360 1 

IL30D3PO* 380 6CA 1 

ILBOS3M0* A50 DB 1 



ILBOSTP0* 
$ENTAS 



B30 
B70 



3D 



ENTRY 
NAME 



CURSEGM 
ILBOSTP1 



B29 (?) 

B4C 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 



284 
28C 
294 



CONTROL SECTION 
NAME ORIGI 
ABEND50 B88 1C 2 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 



ABEND50 




ABEND50 


2 


288 


ILBODSP0 




ILBODSP0 


1 


290 


ILBOSTP1 




ILBOSTP0 
ENTRY 


1 


50 


,ENGTH SES. 


NO. 


NAME 


LOCATION 


NAME 1 







ILBOSTP0 
ILBOSGM0 
ABEND50 



ILBOSTP0 
ILBO3GM0 
ABEND 50 



NAME LOCAi'ION 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO 



LOCATION REFERS TO SYMBOL IN CONTROL SECTION SEG. NO. 



ENTRY ADDRESS 
TOTAL LENGTH 



20 ^ 
BA8 {Sj 

DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 



* ABDU«P REQUESTED * 



STEP GO 

SYSTEM = 0C7 Ql) 



JOB ABEMD 

COMPLETION CODE 

PROGRAM INTERRUPTION (DATA) AT LOCATION 014BC8 

INTERRUPT AT 014BCE (T) 

PSH AT ENTRY TO ABEND FF15000D C0014BCE 

TCB 005298 



TIMS 173122 DATE 71086 



RB 


0006C888 


PIE 


00000000 


DEB 


0006C80C 


M5S 


00005320 


PK/FLG 


10910408 


FLG 


000002F9 


FSA 


1406CFBO 


TCB 


00000000 


TME 


00005348 


U3EK 


00000000 











TIOT 0006CF10 
LLS 0006CBAO 
PIB E0009F98 



CMP 800C7000 
JLB 00000000 
JSTAE 00000000 



TRN 00000000 
JSS 00000000 
TCr 00000ECE 



Figure 60. Segmented COBOL Program with Abnormal Termination Dump (Part 3 of 4) 
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AC11VJJ KBd 

PKB 011000 HM RON 



SZ/STAB O17B00CO OSE/EP 00014050 PSW FF15000D C0014BCE C 000000 rfl/LNK 00005298 



SVRB ObCBlO NM SVC-401C SZ/STAB 0012D172 USE/EP 000041A8 PSW FF040033 40004370 a E803E8 WT/LNK 00014000 

RG 0-7 CDFEB448 00014BC8 0006D000 0006DOOO 32014BCE 5001436E 000140D8 0001429F 

RG 8-15 00O142A0 00014342 00014BB8 0001*4050 000142B8 000110EO 00014BB8 0C0143E0 

SVRB 06=888 NM SVC-105A SZ/STAB 000CD172 USE/EP 000041A8 PSW FF040235 8000D53C G C803C8 WT/LNK 0006CB10 

RG 0-7 00014BD8 00014C30 000012C0 400041AA 00000000 00000000 0O014BD8 8000it35£ 

RG 8-15 0000531E 00014CA6 0006D000 00005298 00005298 00014C40 600043FA 00014BC8 

LOAD LIST 

LPRB 06CBA8 NM IEWSZOVR SZ/STAB 00112010 OSE/EP 0106CBC8 PSW FF040232 800073F0 Q 000000 tfr/LNK 0006CB10 



P/P STORAGE BOUNDARIES 00011000 TO 0006D000 

FrtEE AREAS SIZE 

OlIEtO 00057590 

06C858 00000030 

06CDB0 00000008 

06CEE8 00000028 

SAVE AREA TRACE 

RUN iJAS ENTERED 

SA 06CFBO WD1 00000000 HSA 00000000 LSA 000140EO RET 000064CC EPA 50011050 RO 00000008 





Rl 0006CFF8 


R2 


0006DOOO 


R3 


0006DOOO 


Rl 


0006CF70 




R7 0006CC30 


R8 


0006CF78 


R9 


00000000 


RIO 


0006CFBO 


tfAS 


ENTERED VIA CALL 












0140E0 


MD1 00000000 


HSA 


0006CFBO 


LSA 


00000000 


RET 


00011BB8 




Rl 9200CCC0 


R2 


CDFEB118 


R3 


8F06CE10 


Rl 


OOObDOOO 




R7 00000005 


R8 


0006CA21 


R9 


00000079 


RIO 


900111B2 



R5 00000060 
Rll 0006CFF8 



R6 0000529b 
R12 600113LA 



EPA 00011A80 RO 5001464c 
R5 0006DOOO R6 00011BC2 
Rll 6000CD10 R12 0000CF58 



REGS AT LdTRY TO ABEND 

FL. PT REGS 0-6 00.000000 00000000 



RlGS 0-7 
KcGS S-15 



00 000000 00000000 



00 000000 00000000 



00. 000000 0000000c 



CDFEB418 
000112A0 



00014BC8 
00011312 



0006DOOO 
00011BB8 



0006DOOO 
00011050 



32014BCE 
00011238 



5001436E 
000110EO 



000140D8 
00011BB8 



0001l29t 
000113b0 



P/P STORAGE 



011000 
014020 
014040 
014060 
014080 
0140A0 
0140CO 
0140E0 
014100 
014120 



D9E4D540 
00014030 
00000000 
C4404040 
00014BB8 
00000000 
00000000 
00000000 
8F06CE10 
6000CD10 



40404040 017B00C0 00014050 FF15000D C0014BCE 00000000 00005298 

C014CCOO 00000500 OO0O0B00 0006CF78 00014020 02020000 00000000 

00000000 00000002 01000002 90ECD00C 185D05F0 4580F010 C1C2C5D5 

C1D5E2C3 0700989F F02407FF 96021034 07FE41F0 000107FE 00014342 

00014050 000112B8 000110E0 000142DC 00014320 00000000 00000000 

00000000 00000000 00000000 00000000 00000000 booooooo 00000000 

00000000 08000056 00000001 00000001 00000000 F1F2F3C4 00000000 

0006CFB0 00000000 00014BB8 00014A80 5001464C 9200CCC0 CDFEB118 

0006D0O0 0006D000 00011BC2 00000005 0006CA21 00000079 800111B2 

0000CF58 7000004B 00000000 00000000 O00142DC 00000000 00000000 



ANSC. . . 0. 



014AE0 
014B00 
014D20 
014B40 
C14B60 
014B80 
014BAO 
014BC0 
014BE0 
014COO 
014C20 
014C40 
014C60 
014C80 
014CAO 
014CC0 
014CE0 
014D00 
014D20 
014D40 
014D60 
014Q80 
014OA0 
014DC0 
LINtS 



4020FOD8 
4780F0B4 
F0A8D203 
07FE5120 
47F0F006 
58E0F01C 
17FF000C 
1005F2F2 
0007000C 
002C0020 
0100DC40 
00000000 
00014C88 
00014EEO 
98E0D15C 
D0B61BFE 
000858FO 
01704740 
47A0D0EA 
4E1D0150 
411E0004 
00014D80 
0006C6E5 
40404040 
014DEO 



422D01A7 
481D01A4 
50006000 
F0D447F0 
B10O1BO0 
48FD005C 
00014BB8 
10101040 
0100721A 
0006C80C 
OOOODCIO 
00057BA8 
00005298 
00000017 
12EE4780 
10FD0168 
F03005EF 
D0CE4720 
400D005C 
F333D1E2 
191F0785 
OOOOOEEO 
0006C7E8 
40404040 
-014E00 



41000032 19204740 
88100002 585D019C 
41550001 41660004 
F0244898 CDFEB4 
9101F03C 071E4 
58D0E004 58EDO0OC 
02000000 0A2D58FF 
FA306000 C01858F0 
00280C9A 00000001 
9200D588 0000D518 
0000007D 00000001 
40104040 40404010 
00004539 00011C20 
7F000000 10201010 
D096D27C F000D16C 
D203E000 D16811FE 
111D0048 58E01008 
D0CC1A01 1A011A01 
07F5481D 005E4111 
D15496F0 D1E5D201 
47F0D082 D7C1C7C5 
00000000 FOFOFOFO 
036F4040 007D4040 
F0F4F040 C6F0C6F4 
SAME AS ABOVE 



UU4 

118 (7\ 
100 N-' 



F0B49140 
586D0198 
4610F09A 
0000007F 



F0DA1710 
12111780 
503DOOOC 
7FFFFFFF 



00019601 
980CD011 
000407FF 
C00C07FF 
00004000 
0B000001 
000020BE 
40404040 
800043AA 
00014BD8 
41FF007D 
000450FD 
58F0E034 
9240D170 
0001401D 
D05CD130 
FFFF07FE 
C6F0C6F0 
40F0F1F4 
C6F0F4F0 



F03C50DO 
07FE5820 
01014030 
00001068 
00000001 
00000372 
00014BD8 
60014CF6 
00000000 
O006C470 
50FD0160 
0160411D 
05EF4110 
D277D171 
005E92F1 
47F0D060 
00000000 
6C00005C 
C4C1F040 
40C3F6C6 



F084D500 
F0B49180 
98ECD00C 
0fl32fa 088 
F03807FE 
000140E0 
58F0C004 
00000100 
04000001 
30040048 
00005298 
0000D518 
A000448C 
0006CDC0 
411F007D 
00489220 
0001480D 
D1704110 
D170D203 
98E0D15C 
00000000 
80004262 
4O40F0FO 
F0C3F6C6 



F0D9E000 
60004710 
94BFF0DA 
80004780 
9400F020 
01B4900F 
051F0001 
2DOOOO00 
54000000 
4106CDBP 
00000000 
0006C7E8 
00014DB1 
0001.0005 
191047CO 
100558F1 
005C9560 
00381901 
D1DDD12C 
12EE.0785 
00014C30 
0006C470 
F0F6C3F6 
F4404040 



♦ . Ow. . . 
*. . 0. . . . 








. . 


. . ■ 0. . . 0. N. OR. . * 
* 












. 0. * 




00, 








* 


*. . 0. . . . 








* 


* 










* 


* . 22 











* 


* 










* 










* 


* 












* 












* 




*....... 












* 
























* 













PAGE * 
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Since the sample proolem program shown 
in Figure 61 was interrupted because of a 
data exception, the programmer should 
locate the contents of field B at the time 
of the interrupt. The numerals encircled 
in the two techniques given below refer to 
information similarly labeled in the sample 
program. 

Usin g the General Regist ers : The general 
registers usually contain information that 
can be helpful to the programmer who is 
trying to locate specific data. 



1. 



Locate data-name B f (T) , in the 
glossary. It appears under the column 
headed SOURCE-NAME. Source-name B has 
been assigned to base locator 3 (i.e., 
BL=3) with a displacement of 058. The 
sum of the value of base locator 3 and 
the hexadecimal displacement value 58 
is the address of data-name B. 

2. The Register Assignment table, \2\ , 
lists the registers assigned to each 
base locator. Register 6 has been 
assigned to BL=3. 



3. 



The contents of the 16 general 
registers at the time of the interrupt 
are displayed at the beginning of the 
dump, rT\ . Register 6 contains the 
addressMM) 01 4 2 . 



4. 



can 



The location of data-name B, (V) , 
now be determined by adding the 
contents of register 6 and the 
hexadecimal displacement value 58. 
The result, 14258, is the address of 
the leftmost byte of the 4-byte 
field B. Field B contains F1F2F3C4. 
This is external decimal 
representation and does not correspond 
to the USAGE COMPUTATIONAL- 3 defined 
in the source listing. 



Using the TGT Memory Map: If the general 
registers appear not to contain meaningful 
information, it may be that errors in the 
problem program have destroyed their 
contents. In such a case, the alternate 
method of locating data-names given below 
should be helpful. 

1. The location assigned to a given 

data-name may also be found by using 
the BL CELLS relocation value given in 
the TGT Memory Map, (!T) . To find the 



location of the BL cells, add 003FC 
(from the TGT table) to the entry 
point address 1 , 14020, of the object 
module, (6J. In this example, the BL 
cells begin at location 1441C: 



003FC + 14020 = 1441C 

2. The first four bytes are the first BL 
cell, the second four bytes are the 
second BL cell-^etc. Note that the 
third BL cell,(/n, contains the value 
14200. This is the same value as that 
contained in register 6. 

Note: Use of the FLOW and STATE 
options eliminates the need for the 
calculations described above. All 
that is needed for program debugging 
is the output from FLOW and STATE 
printed at the end of the listing, Cs) , 
and described below. 

A. Specification of either FLOW or 
STATE causes the PROGRAM-ID, the 
completion code, and the PSW for 
the last problem program executed 
before the abnormal termination to 
be printed out. 

B. If STATE is in effect, the printed 
output includes the compiler- 
generated card number for the last 
verb executed. 

C. If FLOW is in effect, the words 
FLOW TRACE are printed out, 
together with the PROGRAM- ID and 
the card numbers of the procedure- 
names executed for all COBOL 
programs with the FLOW option in 
effect. 

For further discussion of the FLOW and 
STATE compiler options, including 
their relationship to the NUM option 
and to the SYMDMP option, see the 
chapter entitled "Symbolic Debugging 
Features. " 



x For nonsegmented programs, the entry point 
address and the load point address are the 
same. (For a discussion on computing the 
load point address for a segmented 
program, see the section "Debugging a 
Segmented Program.") 
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COCCI 
00002 
0CCC3 
CCCC4 
000C5 
C00C6 
0C0C7 
00008 
CCCCS 
C0C1C 
00C11 
0CC12 
0C013 
00014 
CCC15 
OCvitr 
00C17 
0CC18 
C0019 
CCC2C 
0CC21 
00022 
CCC23 
0CC24 
CC025 
CCC26 
0C027 
CCC28 
CCC29 
CC030 
CCC31 
0CC3Z 
OCC3 3 
CC034 
CCC35 
CC036 
CCC37 
0C03F 
CCC39 
CCC4C 
C0041 
CCC42 
0CC4? 

CCC45 
CCC46 
0CC47 

ccc4e 
CCC49 

CCC5C 
CCC51 
OCC52 
0CC53 
CCC54 
00C55 
CCC56 
CCC57 
CCC5E 
CCC59 
CCC60 
CCCfcl 
C0062 
00063 
CCCi4 
CCC65 

cccet 

CCC67 
0C06R 

cccts 

CCC7C 
CCC71 
CCC72 
00073 
00C74 
CCC75 
CCC76 
CCC77 
CC076 
0CC79 
CCCFO 

occei 

CCC82 
CCC63 



100010 
100020 
1C003C 
100040 
10005C 
1C0060 
1CCC7C 
100080 
1C0C9C 
1CC1CC 
100110 
100I2C 

iccnc 

1CC14C 
1C015C 

100170 

lcoiec 

1C019C 

IC02CC 

1CC21C 

10022C 

ICC225 

1CC23C 

10024C 

1C025C 

1C026C 

100270 

1CC28C 

100290 

1C03CC 

1CC310 

1CC32C 

10C33C 

1CC34C 

1CC35C 

1C036C 

1C037C 

10C375 

1CC38C 

100395 

10C4C5 

1CC41C- 

1C042C 

1CC44C 

1CC45C 

1C046C 

1CC47C 

1CC46C 

1C049C 

1CC50C 

10051C 

10052C 

10C522 

100524 

100526 

1CC53C 

1CC54C 

1C055C 

IC056C 

1C057C 

10C580 

10059C 

KCtcc 

1C061C 
1CC62C 
1C0625 
1C063C 
1C064C 
1CC65C 
1C0660 
1CC67C 
10068C 
1CC69C 
1C07CC 
10071C 
100720 
1CC73C 
10074C 
1CC75C 
1CC76C 
1C077C 
1CC78C 



inFhTiciriTirK niurctnN. 
PRCGRAM-IC. TESTRUN. 

AUTHGR. PROGRAMMER NAME. 

INSTALLATION. NEti YORK PROGRAMMING CENTER. 

CATE-WRITTEN. JULY 12, 1<968. 
CATE-CCMPILEO. MAY 6,1971 

REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 
COBOL USERS. IT CREATES AN OUTPUT FILE AND READS IT BACK AS 
INPUT. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 

SC'jPCE-CCPiJTPB; !5M-?*0-H50; 

OBJECT-COMPUTE^. IBM-360-H50. 
INPUT-CUTPUT SECTION. 
FILE-CCNTPCl. 



SELECT FILE-2 ASSIGN TO UT-2400-3-SAMPLE. 
DATA CIVISICN. 
FILE SECTICN. 
FC FILE-l 

LABEL RECORDS ARE OMITTED 

BLCCK CONTAINS 100 CHARACTERS 

RECCPC CONTAINS 20 CHARACTERS 

RECORDING MODE IS F 

CATA PECCRC IS RECORC-1. 
01 PECCRD-1. 

C2 FIELC-A PICTURE IS X(2C). 
FC FILE-2 

LAeEL FECCPCS ARE CMITTEC 

BLCCK CONTAINS 5 RECCRDS 

PECCPC CONTAINS 20 CHARACTERS 

RECCPDING MCCE IS F 

CATA RECORD IS RECORC-2. 
CI RECCRC-2. 

C2 FIELC-A PICTURE IS X(20). 
WCPKING-STCPAGE SECTION. 

77 KCLNT PICTURE S99 CCMF SYNC. 

77 NCMBER PICTURE S99 CCMF SYNC. 
CI FILLER. 

C2 ALPHABET PICTURE X(26) VALUE "ABCCEFGHI JKLMNOPQRSTUVWXYZ" . 

C2 ALPHA REDEFINES ALPHABET PICTURE X CCCURS 26 TIMES. 

C2 CEPENCENTS PICTURE X126) VALUE "C 12340 1234C 1234C 1234C 1234 

"C". 

C2 CEPFNC REDEFINES CEPENCENTS PICTURE X CCCURS 26 TIMES. 
CI KPK-SECCPC. 

C2 NAME-FIELD PICTURE X. 

C2 FILLFR PICTURE X VALUE SPACE. 

C2 PECCRD-NO PICTURE 9999. 

C2 FILLER PICTLRE X VALUE SPACE. 

C? LCCATICN PICTURE AAA VALUE "NYC". 

C2 FILLER PICTLRE X VALUE SPACE. 

C2 NC-CF-CEPFNCENTS PICTURE XX. 

C2 FILLER PICTURE X(7) VALLE SPACES. 
CI PECCRDA. 

C2 A PICTURE S9I4J VALLE 1234. 

C2 e "ECEFINES A PICTURE S9(7I COMPUTATIONAL- 3. 
PROCEDLRE CIVISICN. 
BEGIN. 

NOTE THAT THE FCLLCWING OPENS THE OUTPLT FILE TC BE CREATED 

ANC INITIALIZES COUNTERS. 
STEP-1. CPEN CLTPUT FILE-l. MCVE ZEPC TC KCUNT NCMeER. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE PECCRCS TC BE 

CCNTAINEC IN THE FILE, WRITES THEM ON TAPE, ANC CISPLAYS 

THEM CN THE CCNSCLE. 
STEP-2. ACC I TO KCUNT, ACD 1 TC NCMBER, MOVE ALPHA (KCUNT) TC 

NAME-FIELC. 

CCMFLTE B = B ♦ 1. 

MOVE DEPEND (KCUNT! TC NC-CF-DEPENDENTS. 

MCVE NCKBER TC PECCRC-NC. 
STEP-3. DISPLAY V.CPK-RECCRC LPCN CCNSOLE. WRITE PECCRD-l FRCf 

HCPK-PECCRC. 
<TEP-4. FEPFCPM STEP-2 THRU STEP-3 UNTIL KCUNT IS ECUAL TC 26. 

NOTE THAT THE FOLLOWING CLCSES OUTPUT ANC RECPENS IT AS 

INPUT. 
MEP-5. CLCSE FILE-l. CPEN INFLT FILE-2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE ANC SINGLES CUT 

EI»FLCYEES WITH NC CEPENCENTS. 
<TEP-fc. READ FILE-2 RECCRD INK WCPK-RECCRC AT ENC GC TO STEP-8. 
STEP-7. IF NO-OF-DEPENDENTS IS ECUAL TO "0" MOVE "Z" TO 

NC-CF-DEPENCENTS. EXHIBIT NAMEC WCPK-RECCRC. GC TO 

STEP-6. 
STEP-8. CLCSE FILE-2. 

STCP RLN. 
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INTRNL NAPE 


LVL 


SOURCE NAME 


CNC=1-148 


FC 


FILE-1 


CNP=l-167 


CI 


FECCPC-1 


CNM=1-188 


C2 


FIELC-A 


CNP=l-205 


FC 


FILE-2 


DNf«=l-224 


CI 


PECCPD-2 


CNW= 1-245 


C2 


FIELC-A 


CNM=l-265 


77 


KCUNT 


DNM=1-28C 


77 


NCMBER 


CNM=l-2<;6 


CI 


FILLER 


CNM=1-315 


C2 


ALPHABET 


DNW= 1-333 


C2 


ALPHA 


CN*=1-351 


C2 


CEPENDENTS 


DNf=l-371 


C2 


DEPEND 


CNM= 1-387 


CI 


hCRK-RECORO 


CNP=l-4U 


C2 


NAME-FIELD 


DNP= 1-431 


C2 


FILLFR 


CNM=1-45C 


C2 


RECCRC-NC 


CN*=1-46 C . 


C2 


FILLER 


CNM=1-48E 


C2 


LCCATICN 


CNM=2-C0C 


C2 


FILLER 


rN;!D = 2-ri<; 


c? 


Kr-rF-nFPFNPFMS 


CNM=2-C45 


C2 


FILLER 


CN^=2-C64 


CI 


FECCPCA 


CNM=2-C84 


C2 


A rz\ 


CNf=2-CS5 


C2 


e— <0 



EASE 


DISPL 


INTRNL NAPE 


CEF1NITI0N 


USAGE 


R Q M 


DCB=01 




DNM=1-148 






CSAM 




F 


EL=1 


OCO 


DNM= 1-167 


OS 


CCL20 


GROUP 






BL=1 


OOO 


DNM-1-188 


cs 


20C 


OISP 






DC8=02 




DNM=1-2C5 






CSAP 




F 


eL=2 


OCO 


DNM= 1-224 


cs 


CCL20 


GROUP 






BL=2 


CCC 


CNP*l-245 


cs 


2CC 


DISP 






BL = 3 


CCC 


DNH*=l-265 


OS 


1H 


CCfP 






eL=3 


002 


CNM=l-280 


cs 


1H 


COHP 






BL = 3 


CCS 


DNM=l-2<36 


cs 


0CL52 


GROUP 






eL = 3 


CC8 


ONM= 1-315 


cs 


26C 


CISP 






EL=3 


CC8 


CNH=l-333 


cs 


1C 


OISP 


R C 




BL = 3 


C22 


DN*=1-351 


cs 


26C 


DISP 






BL=3 


022 


ONM= 1-371 


cs 


1C 


DISP 


R C 




RL=3 


040 


CNP=l-387 


cs 


0CL20 


GROUP 






8L=3 


C40 


ONM= 1-411 


cs 


1C 


DISP 






eL=3 


C41 


CNM= 1-431 


cs 


1C 


OISP 






8L = 3 


C42 


DNH=1-45C 


cs 


4C 


CISP-NP 






BL = 3 


C46 


DNf=l-46<; 


OS 


1C 


DISP 






EL = 3 


C47 


CNM=l-488 


cs 


3C 


DISP 






BL = 3 


C4A 


0Nf=2-0CC 


cs 


K 


CISP 






BL=3 


04B 


DNP=2-C1S 


DS 


2C 


CISP 






BL=3 


C4D 


DNH=2-C45 


cs 


7C 


OISP 






BL = 3 


C58 


DNP=2-C64 


cs 


CCL4 


GROUP 






BL = 3 


C58 


CNM=2-C84 


cs 


4C 


DISP-NV 






BL=3 


C58 


0NP=2-0<35 


cs 


4P 


COfP-3 


R 





fEPCPY MAP 



TCT 



CC24C 



TBL 



®— 



SAVE AREA 
ShITCH 
TALLY 
SCRT SAVE 
FNTPY-SAVE 
SCRT CERE SIZE 
RET CCCE 
SCPT PET 
V>CPKIf\G CELLS 
SCPT FILE SIZE 
SCPT VCCE SIZE 
PGT-VN TEL 
TCT-VN TEL 
VCCNFTR 
LENGTH OF VN 
l.ARFL PET 
CLRRENT FRICRITY 
UMSED 
IMT1 ACCCN 
CEeLG TABLE PTR 
IjMJSEC 

CVEPFLCW CELLS 
EL CELLS 
CECRAC CELLS 
TE*P STCPAGE 
TEMP S10PAGE-2 
TE*P STCPACE-3 
TEfrF STTFAGE-4 
en. CELLS 
VLC CELLS 
SBL CELLS 
INCEX CELLS 
SUPACP CELLS 
CNCTL CELLS 
PFMCTL CELLS 
FFfSAV CELLS 
VN CELLS 
SAVE AREA =2 
SAVE AREA =3 
XSASfe CELLS 
XSA CELLS 
FARAP CELLS 
PPTSAV AREA 
Ct-ECKFT CTP 
VCCN TEL 
CEBLG TABLE 



CC24C 
CC288 
CC28C 
CC2SC 
CC2S4 
CC298 
CC29C 
CC2SE 
CC2A0 
CC3DC 
0C3C4 
CC3C8 
CC3DC 
CC3EC 
CC3E4 
CC3E6 
CC3E7 
CC3E8 
CC3FC 
CC3F4 
CC3F8 
0C3FC 
CC3FC 
CC4C8 
CC4C8 
CC410 
CC41C 
CC41C 
CC41C 
CC41S 
CC418 
CC41E 
CC418 
CC42C 
CC42C 
CC42C 
CC424 
CC42e 
CC428 
CC43C 
CC43C 
CC43C 
CC434 
CC434 
CC438 
CC438 



Figure bi. Sample Program (Part 2 of 5) 
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LITERAL POOL (HEX! 

CC4A8 (LIT*0) CCCOCOCl 1COOC01A C04805EF A80000C0 CO00OOC0 

CISPLAY LITERALS (8CCI 
CC48C (LTL+2C) 'hCPK-PEGCflC' 



PGT 

CVERFLCW CELLS 
VIRTLAL CELLS 
FRCCEOtRE NAME CELLS 
C-ENEPATEC NAME CELLS 
rC.B..AJ3 .CRESS CELLS . 
VM CELLS 
LITERALS 
CISPLA* LITERALS 



CC45C 

CC45C 
CC45C 
CC46C 
CCA8C 
0C498 
CCA AC 
CCAA8 
OOABC 



REGISTER ASSIGNMENT 
PEG 6 eL = 3" \i/ 



REG 7 
PEG 8 



P.L =1 
RL = 2 



hCRKING-STCFAGE STARTS AT LCCATICN OOIEC FCR A LENGTH OF CCC6C. 



♦STEP-2 



67 

68 



COMPLTE 
MOVE 



OCOACR 
CCCAC8 
CCCACA 
CCCACE 
CCC«CC 
CCOACA 
CCCAD6 

CCCACA 
CCC4DE 
CCCAEC 
CCCAEA 
CCCAE6 
CCCAEA 
CCCAEE 
CCCAFC 
CCCAFA 
CCCAFA 
CCC5CC 
CCC5CA 

ccc=ce 

CCC5CC 
CCC5CF 
CCC512 
CC0514 
CCC=lf 
CCC51A 
CCC51F 
0CC522 
CCC528 

CCC52E 
CCC52E 
CCC532 
CC0534 
CCC53F 
CCC53A 

ccc53E 

CCC5A2 
CCC5A6 
CCC54A 
CCC5AF 
CCC552 
CCC556 
CCC55A 
CCC55F 
CCC?62 
CCC?64 
CCC56P 
CCC56C 
CCC57C 
CC0576 
CCC57C 
CCC58C 
CCC584 
CCC588 

ccc^e* 

CCC5PF 
CCC5?2 
CCC596 



CI CC 

58 FC C v OCC 

C5 EF 

5E FC C OIC 

C5 IF 

CC00CC3A 

58 FC C OOC 

C5 EF 

58 FC C OIC 

C5 IF 

CCCCCC3D 

5P FC C OOC 

C5 EF 

?e k 
C2 ci 
D2 CI 
5C K 
"52 8F 
Al IC 
CA 13 
58 IC 
18 21 
58 FC 
C5 EF 
5C 10 
5E 7C 
C2 CI 
C2 01 



C 0A8 
1 032 
1 06C 
1E8 
C IE8 
C IE8 



IRC 
IRC 
OCO 
002 



C OOC 



CCCCCCA1 
48 3C C 05A 



AA 3C 
AC 3C 
A8 3C 
AA 3C 



AC 
Al 
A8 
AC 
1A 



5e AC 
5C AC 
5e EC 
C2 CC 
FA 3C 



5E AC 

5C AC 

58 FC 

C2 OC 



06C 
C62 



C 0A8 



C58 
C58 



000 
OCC 
05A 
CC2 
0C2 
CCP 
CCC 
C5A 

ose 

1C8 
1D8 
OAC 
058 
C22 
COC 
C5A 

058 
IDC 
IOC 
OAB 



CCC 
C5C 



E OCC 



ccc5<;c <;2 ac 6 oac 



ECU 


• 






BCR 


0,0 






L 


15t00C(0tl2) 


V(ILBOCeGA) 




BALR 


14,15 






L 


15,01C(0,12I 


V(ILBCFLWl) 




BALR 


1,15 






CC 


X«000C003A' 






L 


15,CCC(C,12» 


V(ILBOOeGA) 




BALR 


14,15 






L 


15,C1C<C,12I 


V(IieCFLhl) 




BALR 


1,15 






OC 


X'OOOCOOSC 






L 


15,CCC1C,12) 


VI ItBOOeGA) 




BALR 


1A.15 






L 


I.CA8IC12) 


CCE=1 




MVC 


032(2, 11, C6CI12I 




LIT + 8 


MVC 


060(2,1), 062(12) 




LIT+1C 


ST 


1,1E8(0,13» 


SAV3 




MVI 


1E8(13),X'8F« 


SAV3 




LA 


1,168(0,13) 


SAV3 




SVC 


1<3 






L 


1,046(0*121 


CCB=1 




LR 


2,1 






L 


15,C3C(C,1) 






BALR 


1A, 15 






ST 


l,ieC(C,13) 


BL =1 




L 


7.1PCI0, 13) 


8L =1 




MVC 


CC0I2.6) ,C58(12) 


CNM=l-265 


L1T«C 


MVC 


002(2, 6), C5E( 12) 


0NM=l-280 


LIT + C 


ECL 


* 






L 


15.00UO, 12) 


V( ILBOCRGA) 




BALR 


IA.15 






L 


I5.01CIC.12) 


V(lLBCFLM) 




BALR 


1.15 






OC 


X'OOOOOCAl' 






LH 


3,C5A(C,12) 


LIT + 2 




AH 


3.0CC(0,6I 


CNM= 1-265 




STH 


3,CC0(C,6> 


CNM1-265 




LF 


3,C5A(C,12) 


LIT+2 




AF 


3,0C2(0,6I 


CNM=l-280 




STH 


3,0C2(C,6) 


CN"=«l-280 




LA 


A,0C8(0,6) 


CNM= 1-333 




LH 


2,0C0(C,6) 


CNM=l-265 




MH 


2,05A(0,12I 


LIT + 2 




AR 


A, 2 






S 


A,C56(C,12) 


LIT+O 




ST 


A,lce<C,13) 


SBS=1 




L 


1A, 1C8(C, 13) 


SBS=1 




MVC 


OAC( 1,6) ,0CC(1A) 


CNP=1-A11 


CNM=l-333 


AP 


C5e(A,6),C5C( 1,12) 


DNM=2-S5 


LIT+A 


LA 


A,C22(0,6) 


CNM=1-371 




LH 


2,CCC(C,6) 


CNM=l-265 




M|- 


2.C5AI0, 12) 


LIT + 2 




AR 


A,? 






S 


A,C5e(C,12l 


LIT + C 




ST 


A,ir.C(0,13) 


SBS=2 




L 


1A,1CC(C,13) 


SES = 2 




MVC 


OAB( 1,6),CCC( 1A) 


DNM=2-1S 


CNN=1-371 


wvi 


0AC(6) ,X'AO« 


CNM = 2-1<5+1 
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♦STATISTICS* SCUPCE PECCPCS = 83 CAlA uiVISIOni STaTcKEbTS » 25 PROCEDURE DIVISION STATEfE! 
♦OPTIONS IN EFFECT* SIZE = 8192C BUF = 2768 LINECNT = 57 SPACElt FLAGH, SEQt SOURCE 
*CPTICNS IN EFFECT* CHAP, PMAP, NCCLIST, NCSUPPAP* NCXREF, NCSXREF, LCAC, NCCECK, CUCTEt NOTRUNC, 
♦CPTICNS IN EFFECT* NCTEPf, NCNUH. NOBATCH, NONAHE, CC*PILE=01, STATEt LIB; VERB, ZWB, SYST 



FICM= 



C*"C ERRCR MESSAGE 

= e IKF21SCI-* PICTURE CLALSE IS SIGNE.Cf VALUE CLALSE UNSIGNEC. ASSUfEO POSITIVE. 



* A6CL"P PECLESTEC * 
JCe TESTRUN STEP CC 

CCPIETICN CCCE SYSTEN = 0C7 
PRCGRAf INTERRUPTICN (CATA) AT LCCATION C14«<;< 
IMFRQlPT AT CC4C34 

PSU »T ENTRY TC ABEKC CCC4CCCD ECC1459C 
TCe CC5298 



TIME C64342 DATE 71126 



RE CCC6CA40 

HSS CCCC532C 

FSA 14C6CFeC 

USER CCCCCCCC 



PIE CCCCCCCC 
PK/FLG 1C91C4C8 
TCB CCCCCCCC 



I5EB CCC6C9C4 
FLG 000004F9 
TMF 00CC5348 



ACTIVE RPS 
PRP C14CCC 



^ 



TICT CCC6CEE8 
LLS COOCCOOC 
PIE ECCC9F98 



CPP 


800C7000 


TRN 


OOOCOCOC 


JL8 


CCCCCOCC 


JSE 


CCOCOOOC 


NSTAE 


ACC6CCF8 


TCT 


OC0C4C8C 



S7/STAB C51BCCCC USE/RP C0C1402C PSh FF15CCCC 40^^34 C OCOCOC fcT/LNK 0C0C5298 



KN SVC-eCIC SZ/STAP 0C12C172 
RG C-"t CCCCCC3C CCCllS-iE 
PC fl-15 CCC14C2C OCC1462fc 

Nt- S\fC-4ClC SZ/STAE C012C172 
PG C-7 FACCCC6E 8CCC7CCC 
PC e-15 OCC14COC OOOCAAE2 

Nf S\,C-1C5A SZ/STAB C0CCD172 

rg c-7 crci6Poe oocie«;3c 

RC e-15 CCCC531E 00C16<;At 



USE/EP 0CCC41A8 PSW FFF5000D ECC1459C Q ieC318 hT/LNK OCC1400C 

CCCOCOOl OCCCOCC1 CCCU208 50C1485E CCC14ZCC CCCCCB98 

CCC14C2C CCC14C2C CCC1447C CCC1426C 0CC1A2C8 0CC16C06 

USE/EP 00CC41A8 PSW FF04C033 4CCC437C Q E8C3E8 hT/LNK 0CC6CO6e 

8CCC5E64 OG00647C CCCC5298 CC06CC68 0006CCFE CCCHOOC 

C0C6CDC8 C0CC5EC4 CCCC5296 CCCtCAEe 40CC41AA CCCCOOOO 

USE/EP CCCC41A8 PSW FF04C235 8CCCC53C Q C8C3C8 kT/LNK CCCtCAAC 

CCCC12CC 4CCC41AA CCCOOCOC CCCOOOOO 0CC168C8 80CC435E 

0CC6C0CC CCCC52^8 CC005298 CCCltSAC 6CCC43FA 2CC14596 



P/P STCRACE eCUNCARIES CCC14CCC TC CCCtCCCC 

Figure 61. Sample Program (Part 4 of 5) 
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PEGS »T ENTRY TC ABEKC 

FL.PT.RECS C-6 CC.CCCCCC CCCCCCOO 



REGS C-7 
REGS 8-1? 



00000030 
00014020 



0001455E 
00014826 



OO.OOOOOC OOCCOOOO 



00000001 
00014020 



00000001 
00014020 



co.cccooc cccocccc 



00014208 
00014470 



50014858 
00014260 






cc.ocoocc cooooooo 

'00014200 0006CB98 
0WPT2TJ*- 00016006 



P/P S1CRAGE 



© 



C14CCC 

ci<.c2: 

C14C4C 
C14C6C 

ciAcec 

C.iACAC. 
C14CCC 

ni^cec 

C1*1CC 
Ol4l2 r 

C1416C 
C141PC 

o imac 

C141CC 
C141EC 
C1«2CC 
C1422C 
C1424C 
C1426C 
C142*C 
CH7AC 
C142CC 

I [NFS 
C144CC 



C9E4054C 4C4C404C 

SOECCOGC IP5CC5FC 

96C21C34 C7FE41FC 

CCC144FF. CCCHEC* 

occccccc rcccoccc 

C.C.C-C-C-CX.C .-CC-CCCCCC- 
CCCCCCC1 cccccccc 
CCCCCCCC CC81S3CC 
CCC6CE2C =2CCCCCr 

ccc6ce*c cccccoi* 
cccccccc cccccccc 

CCCCCCCC CPC14C46 
CCCCCCCC CCCCCCCC 
42CCCCC1 9CC1415C 
CCCCCCCC CCCCCCCC 
CCCCCCCC CCCCGCCC 
CCC1CCC1 CCCCCCCC 
E8ESFCF1 F2F3F4FC 
CHCCC.CC CCCC4CC.5 
CCCCCCCC CCCfCFPC 
CCC6CCCC CCC14C2C 
CCC1<CZC CCCM47C 
CCCCCCCC CCCCCCCC 

C142EC-CH3EC 
CCCCCCCC CCCCCCCC 



C1442C 
C 1^i<i<iC 



CCC14C2C CCCK?CC 
CCCCCCCC CCC1462C 



C51BCCCC CCC14C2C 

4580F010 E3C5E2E3 

CCC1C7FE 0CC14B26 

CCCCCCCC CCCCCCCC 

CCCOCCCC occoocco 

XC CCC.C..CC-. nncc.r.cc.r 

CCCCCCCC OCCCCCCC 

02C6ce<;o oooc^occ 

CCCCCFfE 06C15P78 
OCCC0001 OCCCCCCC 
OCCCCCCC CCCCCCOO 
CCCCCCC1 CCCCCCC1 
CCCCCCCC OCCCCOCC 
E2C1C4C7 03C5404C 
CCCCCCCC CCCCCCCC 
CCCCOCCC CCCOCOCC 
C1C2C3C4 C5CfC7CE 
F1F2F3F4 FCF1F2F3 
E8C34CC0 0C4C4C4C 
CCC6C06C 5CC14554 
50C14858 0CC1A2CC 
3fcCCCC4E CCCCCCCC 
CCCCCOCC OCCCCOOC 

SAME AS ABOVE 
CCCCCCCC OOOCCCOC 
CCCCCCCC COOCOCOO 
eFCL4CC4 CCCCCCCC 



^->. iFPCGPA* TESTRCN (J) 
^-^ IcCHPLETICN CrCE = C( 



FF15C000 
CSE4D54C 
0CC14020 
CCCCOCCO 
OCCCCCCC 
c.cic.cncc.G 
8CCCCCCC 
0CCCCC01 
CCC9CC64 
C0CCDE68 
CCCCOCCC 
CCCCCCCC 
OCCCOCCC 
C2CC000C 
CCCCCC14 
CCCCOCCC 
C9C1C2C3 
F4FCF1F2 
404C4C4C 
CCC16CC6 

ccc6ce<;8 

CCCCOCCC 
OCOOOOOC 



6C004C34 
C1D5E2C3 
00C14C2C 
OOOOOCCO 
CCOOCCCC 
c nnn npnri 
CCOOCCCC 
46CCC0C1 
2EC12828 
C5EFCCCC 
CCCOCCCC 
CCOOCOOO 
CCC0CCC1 
COOOOOCO 
CCCOCCCC 
COCCOCCC 
C4C5C6C7 
F3F4FQF1 
COCOOOCO 
CCC00030 
CC014020 
CCC144E8 
CCOOCOOO 



CCOCOOCO 
C7CCS89F 
CC01447C 
CCCCCCCC 
CCCCCCCC 

..0-S0-1-4-CA6 
CCCCCCCC 
90C14CA4 
42C6CE3C 
CCCCCCCC 
CCCCOCCC 
CCCCCCCC 
CCCC4CCC 
0C015e78 
CCCCCCCC 
CCCCCCCC 
C8C9E2E3 
F2F3F4FC 

\F1F2F3CV 




5C01455A 
CCC14E26 
CCOCCCCC 
CCCCOCCC 



cccccc/7\ 
cT^ccTvl/ 



CCC1 
CCC14C20 
CCCCCCCC 
CCCCCCCC 



CCC14C2G CCC0C<3P CCC6CFFE CCC6CB98 
OCOOOOOC CCOOCOOO CC0142C8 CCCCCCCO 
CCCCCCCC CCCOO0C1 23CCC7E4 CCCCCCCC 



.O..O.TESTPUS tKir . 
.C... 



AeCCEFCHJKLHNCPCRSTLVhX' 

YZ01234C1234C1234C 123401 2340.... i 
A .... NYC .. ....1230...." 



M* 



LAST PSfc PEFCPE ABEKC = FFF5000D E001459C 



BJ L/ST CAPC M^EEF/VEFE MNEEP EXECCTEC ~ CAPC MJPBER 000067/VERB NUMBER 01. 



UM TFST-FLN CCCC5E CCCCC1 CCCC65 
ENC CF CCBCL CE8LCGING AICS 



FLCh TRACE 



Figure 61. Sample Program (Part 5 of 5) 
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DCB 



21 

■T 



24 

T 



j. T T 

\ | DCBBUFCB | 

L ± -r -L 



Buffer 
Area 



Logical 

Record 
Area 



j 



8 12 

"T T - 

|A (Area) j 
.j. T ,_-L- 



Buffers 



< BUFCB + 




control 

data 



variable 
data record 
origin 



displacement 
field 

L j 

Figure 62. Locating the QSAM Logical Record Area 



Loc a ting Data Are as f or Spanned R ecords 



QSAM: QSAM (seguential) spanned records 
allocate a Logical Record Area in which 
complete logical records may be assembled 
(see "Record Formats"). Figure 62 
illustrates the relationship between the 
DCB, the Buffer Areas, and the Logical 
Record Area. 



1. The DCB contains the DCBBUFCB field at 
a displacement of 21 bytes from the 
origin of the DCB. The contents of 
DCBBUFCB points to the origin of the 
Buffer Control Block (BUFCB) in the 
Buffer Area. 

2, The BUFCB field contains an 
Area-Address (A(Area) ) at a 
displacement of 8 bytes from the 
origin of the Buffer Area. The 



Area-Address points to the origin of 
the Logical Record Area. 

3. The Logical Record Area contains a 
displacement field at a displacement 
of 5 bytes from its origin. This 
field contains a value from to 8 
indicating the number of bytes the 
record has been displaced. The 
contents of this 1-7 byte field must 
be added to the value 24 (the first 
byte in the variable data record 
origin area) in order to locate tne 
beginning of the logical data record 
within the Logical Record Area. Note 
that the first 4 bytes of the Logical 
Record Area are control data 
indicating the length of the Logical 
Record Area (including the 4 bytes of 
control data). 

Note: The Logical Record Area is not 
allocated for QSAM records formatted in V, 
U # or F mode. 
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variable 4 
< bytes ><-bytes->< 



variable 
bytes 



> 



r -- 




T ~ T T 




\ 


1 


REC-ID 


1 LL | 11| 


Maximum 01 






X - X X — 





Logical Record Area 



< 



18 
bytes 



variable 4 
-> < — bytes — ><-bytes-><- 



T T- 

I LL | 
X X. 



_ T T _ T _ T _ 

BUFCB | REC-ID | LL | 11 | Data Segment \ 
x x x x \ 



111 

-X. 



variable 
—bytes 



> 



Buffer 
Control Block 



Segment Work Area 



t 



j 



Figure 63. Logical Record Area and Segment Work Area for BDAM and BSAM Spanned Records 



BSAM and BDAM : BSAM and BDAM (direct) 
spanned records allocate a Segment Work 
Area. This work area is used for temporary 
storage of record segments before a 
complete logical record is assembled in the 
Logical Record Area. Figure 63 illustrates 
the Logical Record Area and the Segment 
Work Area. 



Note: The segment work area is not 
allocated for BSAM and BDAM records 
formatted in V, U, or F mode. 



The following discussion illustrates the 
relationship between the DCB, the Logical 
Record Area, and the Segment Work Area as 
shown in Figure 63. 



BDAM 



1. 



2. 



The DCB address plus 100 bytes points 
to the beginning of the BUFCB (Buffer 
Control Block). 

The contents of the BL assigned to the 
level-01 entry in an FD points to the 
Logical Record Area labeled "Maximum 
01" in Figure 63 (see Figure 59 for an 
example of the BL pointer. ) 



B SAM output 

1. The DCB address plus 76 bytes points 
to the beginning of the BUFCB (Buffer 
Control Block) . 



2. The DECB address plus 12 bytes points 
to the beginning of the Logical Record 
Area. 



BSAM input 



1. The DECB address plus 12 bytes points 
to the beginning of the Segment Work 
Area. 



2. The DCB address plus 100 bytes points 
to the beginning of the Logical Record 
Area. 



Loca t ing TCAM Data Areas 



In a teleprocessing application, control 
blocks, called queue blocks , are created 
for a given partition/region. For the 
RECEIVE statement, the number of queue 
blocks created agrees with the number of 
queues accessed. For the SEND statement, 
however, only one queue block is created 
for each partition/region. The encircled 
numerals in Figures 64 and 65 refer to the 
numbered paragraphs below. 

1. The TGT address plus 440 bytes points 
to the SUBCOM field (see Figure 125 in 
Appendix J: "Fields of the Global 
Table"). The fullword at X* 50' bytes 
into SUBCOM points to the first 
RECEIVE queue block. The fullword at 
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2. 



X'54' off SUBCOM points to the SEND 
queue block. In both cases, the first 
field (IHADCB) contains the data 
control block (DCB). 



At X' 58' bytes into either a RECEIVE 
or a SEND queue block, the first byte 
of the 4-byte BUFRADR field indicates 
whether the address that follows 
represents a TCAM buffer or a BSAM 
buffer. If the two high-order bits 
are on, the address contained in the 
next three bytes is for a TCAM buffer. 

Note: For TCAM there is only one 
buffer; for BSAM there is one buffer 
for each queue. 



Relative 
Location 



58 

5C 

5E 

60 

74 

78 

7A 

90 

98 

99 

9A 



Field 
IHADCB 1 
BUFRADR 2 
BUFSIZE 3 
SUMGIVEN 4 
DECBQB 5 
MOREBLKS 6 
AMTLEFT 7 
DATIMSOR 8 
QNAMEQB 9 
EORCHAR 10 
HELDOVER 13 



ISITPART 14 | 
L J 

Figure 64. Fields of the RECEIVE Queue 
Block 



10. 



11. 



Relative 
Location 



58 

5C 

5E 

60 

61 



Field 
Twanrp 1 



BUFRADR 


2 I 


BUFSIZE 


3 I 


MOREROOM 


7 I 


ENDICATR 


8 I 



EORCHAR 10 | 
L J 



12. 



13, 



14, 



Figure 65. Fields of the SEND Queue Block 



In either a RECEIVE or a SEND queue 
block, the next field (BUFSIZE) 
specifies the size of the buffer, 
whose format is pictured in Figure 66. 
(For a list of codes used in the TCAM 
control byte, see Table 24.) 



The SUMGIVEN field of the RECEIVE 
queue block indicates the number of 
bytes of data given to the user for 
this request. 



The DECBQB field of the RECEIVE queue 
block contains the data event control 
block (DECB). 



In the RECEIVE queue block, the 
MOREBLKS field provides the address of 
the next queue block. If the first 
byte of this field is zero, there are 
no additional queue blocks. 



For BSAM only, the AMTLEFT field of 
the RECEIVE queue block indicates the 
amount of data being held in the 
buffer from the last request. 



For BSAM only, the MOREROOM field of 
the SEND queue block indicates the 
number of unused bytes left in the 
buffer. 



The 22-byte DATIMSOR field of the 
RECEIVE queue block contains the date 
and time of the last message received 
from this queue, as well as the source 
of the message. 

The ENDICATR field of the SEND queue 
block contains the end indicator (in 
zoned decimal) specified in the COBOL 
source statement. 

The QNAMEQB field contains the ddname 
for the queue block specified in the 
COBOL teleprocessing program. This is 
the name the COBOL programmer used in 
the SYMBOLIC QUEUE clause of the CD 
entry. 

The EORCHAR field in both the RECEIVE 
queue block and the SEND queue block 
contains the record delimiter 
specified in the MCP. 

The HELDOVER field in the RECEIVE 
queue contains a character that, in 
some instances, is the next data 
character. 

The ISITPART field in the RECEIVE 
queue block is a switch byte. 
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V TCAM Source ID 
prefix control 
Byte 



Data 



Not e; The prefix, the TCAM control byte, 
and the source ID must be user specified 
for a SAM file. However, if the user 
invokes the SEND statement to create a 
SAM file for subsequent input, then the 
COBOL compiler adds bytes 1 through 13 
(see Figure XY in the chapter entitled 
"Using the Teleprocessing Feature"). 

Figure 66. Structure of a TCAM Record 



INCOMPLETE ABNORMAL TERMINATION 



If a job is abnormally terminated and 
the abnormal termination process goes to 
completion, the following procedures are 
carried out: 

• A dump (ABDUMP) is produced by the 
system. 

• The data sets in the job steps are 
disposed of as specified in the DISP 
parameter (i.e., kept, deleted, etc.). 
This is indicated in the job scheduler 
disposition messages produced for the 
job step. 

• Temporary data sets, including those 
passed from previous job steps, are 
deleted. 



When the abnormal termination process 
does not go to completion (i.e., no end of 
dump message is present), none of these 
procedures will be carried out. Those 
data sets in the job step that were in 
existence previous to the point at which 
the error condition occurred will remain 
in effect. For data sets on direct access 
volumes, the names will remain tabulated 
in the Volume Table of Contents (VTOC) of 
the volume (see "Additional File 
Processing Information" for details on the 
VTOC). The result of an incomplete 
abnormal termination is that space needed 
by a subsequent job will be unavailable, 
or, if the same job is then rerun, 
duplicate name definition will result for 
those data sets that are newly created in 
the job step. This is true for temporary 
data sets for which the system has 
assigned the name, as well as data sets 
for which the programmer has assigned the 
name. 



Table 24. Codes Used in the TCAM Control 
Byte 

r t 

i Code j Meaning 



X' Fl' 
X'F5' 



X'40" 
X'FU' 



X'F2' 



X« F6 f 



The first block of a multiblock 
message 



The first block of a multiblock 
indicated 






An intermediate data block 

An intermediate data block, with 
end of segment indicated 



The last block of a multiblock 
message 

The last block of a multiblock 
message, with end of segment 
indicated 



X'F3'|A single block message 

X'F7'|A single block message, with end 
of segment indicated 



SCRATCHING DATA SETS 



To avoid duplicate name definition and 
to ensure that space will be available for 
newly created data sets, the programmer can 
scratch his direct-access volume data sets 
by using the utility program J^HjgEI2GM. To 
scratch such a data set means to remove its 
data set label (which includes its name) 
from the VTOC and to make the space 
assigned to it available for reallocation. 
Scratching does not uncatalog any cataloged 
data sets. This is done by the UNCATLG 
option of the IEHPROGM. 



Note: 



The information in this section 



about scratching data sets applies only 
when running under MFT. Under the MVT 
option, direct-access volume data sets are 
scratched automatically. For use of the 
system utilities under MVT, see the 
publication IBM_OS_Utilities. 

If a DSNAME parameter has been specified 
in the DD statement for the data set, the 
IEHPROGM utility program requires the name 
of the data set. For data sets named by 
the programmer, the specified name is the 
dsname. For data sets for which the 
DSNAME=66name convention has been used, an 
internal name 

name. jobname 
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is assigned by the system, where iobnatne is //SYSIN 

the name of the job and n ame is from the 

S£name. If no DSNAME parameter is 

specified, an internal name is assigned by 

the system. For data sets with no DSNAME 

parameter there exists an option by which 

the programmer can specify that all such 

data sets on the volume be scratched, 

without having to specify their names. /* 



DD 
SCRATCH 

SCRATCH 



DSNAME=GOJOB. TEMP, X 
VOL=2311=222222, PURGE 
VTOC, VOL=2311=222222, X 
SYS, PURGE 



If the programmer wishes to obtain a 
listing of the names of all the data sets 
on a volume, including system-assigned 
internal names, he can use the utility 
program IEHLIST. This program provides a 
listing of the VTOC of the volume. 



Information on how to use these utility 
programs is contained in the publication 
I BM OS Utiliti es. The following example 
illustrates the job control statements that 
might be used to scratch temporary data 
sets: 



In this example, the SYSPRINT DD 
statement specifies the output data set for 
the listing and the DDl DD statement 
specifies the system residence volume. The 
other DD statements specify the volume 
serial number of the volumes that can be 
mounted on which the data sets have been 
written. These DD statements are needed to 
allocate the required devices. The first 
SCRATCH statement eliminates a data set for 
which DSNAME=SSTEMP had been specified on 
the DD statement, and the second SCRATCH 
statement eliminates all data sets on the 
volume for which no DSNAME parameter had 
been specified. 



//SCR JOB 

//STEP1 EXEC 

//SYSPRINT DD 

//DDl DD 

//DD2 DD 
// 



, SCRATCH, MSGLEVEL=1 
PGM=IEHPROGM 
SYSOUT=A 

UNIT=2311, DISP=OLD 
UNIT=2311, DISP=OLD, 
VOLUME=SER=222222 



Note that the possibility of duplicate 
name definition also applies to cataloged 
procedures in which temporary data sets are 
used. 



For those procedures that are executed 
often, the programmer may wish to include, 
at the beginning of his job, a procedure to 
scratch all temporary data sets. 
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PROGRAMM ING TEC HNI QUE S 



Some techniques for increasing the 
efficiency of a COBOL program are described 
in this chapter. It is divided into seven 
paxr."5~i The first four parts- eres-i - in 
general with coding a COBOL program. The 
fifth is concerned with the Report Writer 
feature, the sixth with table handling, and 
the seventh with queue structure 
description. 



OSAM Spanned Records 



rax/Trrrivc-x m err 



POSITIONING, and APPLY RECORD- OVERFLOW, all 
the options for variable length record 
files apply to spanned records. 



GENERAL CONSIDERATIONS 



APPLY RECORD- OVERFLOW Clause 



Spac ing the Sour c e Pro gram Lis t ing 



There are four statements that can be 
coded in any or all of the four divisions 
of a source program: SKIP1, SKIP2, SKIP3, 
and EJECT. These statements provide the 
user with the ability to control the 
spacing of a source listing and thereby 
improve its readability. 



The APPLY RECORD-OVERFLOW clause makes 
more efficient use of direct access storage 
space by using the Track Overflow feature. 
If APPLY RECORD- OVERFLOW is specified, a 
record that does not fit on a track will be 
partially written on that track and the 
remainder will be written on the next 
available track. 



The use Of the APPLY RECORD- OVERFLOW 
option requires that Track Overflow be 
specified at system generation time. 



ENVIRONMENT DIVISION 



CONFIGURATION SECTION 



APPLY CORE-INDEX Clause 



To take advantage of the new instruction 
set on the IBM System/370, the programmer 
should specify IBM-370 as the computer-name 
in the OBJECT-COMPUTER paragraph. 



APPLY WRITE-ONLY Clause 



To minimize processing time with indexed 
files accessed randomly, the programmer 
should use the APPLY CORE-INDEX clause. 
Use of this option causes the highest level 
index to be brought into core storage for 
input/output operations. This speeds 
processing by eliminating the extra time 
needed to search the index on the volume. 



To make optimum use of buffer space 
allocated when creating a standard 
sequential file with blocked V-mode 
records, the programmer may use the APPLY 
WRITE-ONLY clause for the file. Use of 
this option causes a buffer to be truncated 
only when the next record does not fit in 
the buffer. (If the APPLY WRITE-ONLY 
clause is not specified, the buffer is 
truncated when the maximum size record will 
not fit in the space remaining in the 
buffer. ) When using APPLY WRITE-ONLY, all 
the WRITE statements must have FROM 
options. None of the subfields of the 
associated records may be referred to by 
procedure statements and they may not be 
the object of the DEPENDING ON option in an 
OCCURS clause. 



BDAM-W File Org anization 



The use of BDAM-W for file organization 
results in less system generated coding 
than for BDAM-D. When BDAM-D is used and a 
WRITE statement is issued, extra code must 
be generated to compare the contents of the 
ACTUAL KEY of the WRITE statement with the 
key of the preceding READ statement to 
determine whether the system should add or 
update a record. If the keys are the same 
the record is updated. If the keys are 
different the record is added. 
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BDAM-W eliminates this comparison step. 
The system adds a record when a WRITE 
statement is issued and updates a record 
when a REWRITE statement is issued. 



01 MST- WORK- AREA. 

05 SAME-NAMES. (***) 
10 LAST-NAME PIC. . . 

10 FIRST-NAME PIC 

10 PAYROLL PIC. . . 



DATA DIVISION 



OVERALL CONSIDERATIONS 



Pr6il v 6S 



Assign a prefix to each level- 01 item in 
a program, and use this prefix on every 
subordinate item (except FILLER) to 
associate a file with its records and 
work-areas. For example, MASTER is the 
prefix used here: 



05 DIFF-NAMES REDEFINES SAME-NAMES. 
10 MST-LAST-NAME PIC... 
10 MST-FIRST-NAME PIC. . . 
10 MST-PAYROLL PIC... 
01 RPT-WORK-AREA. 

5 SAME- NAMES * ( * * * ) 
10 PAYROLL PIC... 
10 FILLER PIC. . . 
10 FIRST-NAME PIC. . . 
10 FILLER PIC. . . 
10 LAST- NAME PIC... 



PROCEDURE DIVISION. 



FILE SECTION. 

FD MASTER- INPUT-FILE 



01 MASTER-INPUT-RECORD. 



IF MST-PAYROLL IS EQUAL TO HDQ- PAYROLL 

AND MST-LAST-NAME 

IS NOT EQUAL TO PRRV- LAST- NAME 

MOVE CORRESPONDING 

MST- WORK- AREA 

TO RPT-WORK-AREA. 



WORKING-STORAGE SECTION. 
01 MASTER- WORK- AREA. 

05 MASTER- PAYROLL PICTURE 9(3). 

05 MASTER-SSNO PICTURE 9(9). 



If files or work-areas have the same 
fields, use the prefix to distinguish 
between them. For example, if three files 
all have a date field, instead of DATE, 
DAT, and DA-TE, use MASTER- DATE, 
DETAIL-DATE, and REPORT-DATE. Using a 
unigue prefix for each level- 01 and all 
subordinate fields makes it easier for a 
person unfamiliar with the program to find 
fields in the program listing, and to know 
which fields are logically part of the same 
record or area. 



When using the MOVE statement with the 
CORRESPONDING option and referring to 
individual fields, redefine or rename 
"corresponding" names with the prefixed 
unigue names. This technigue eliminates 
excessive qualifying. For example: 



Note : Fields marked with a triple asterisk 
(***) in the foregoing listing must have 
exactly the same names for their 
subordinate fields in order to be 
considered corresponding. The same names 
must not be the redefining ones, or they 
will not be considered to correspond. 



Level Numbers 



The programmer should use widely 
incremented level numbers, i.e., 01, 05, 
10, 15, etc., instead of 01, 02, 03, 04, 
etc., in order to allow room for future 
insertions of group levels. For 
readability, indent level numbers. Use 
l^vel— 88 inimbgjf s for codes Then if the 
codes must be changed, the Procedure 
Division coding for tests need not be 
changed. 
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FILE SECTION 



RtCOKU CONrA-LlJt) ulause 



The programmer should use the RECORD 
CONTAINS integer CHARACTERS clause in order 
to save himself as well as any future 

»-,-v~^>^ ■*•■=, mm /-.•»- 4-V»,~v 4-^r-b- s^G ^/^.i^4- 4 »-.— 4- V, ^ ,3 -> i- -, 

-f^creDn^-^rKXTixmx^az cixc crc*- ovt — orac ox?-ccrjncr^t.~iX^ crrrc: — <occcx^xx~ 

record description positions. Also, the 
compiler can then diagnose errors if the 
data record description conflicts with the 
RECORD CONTAINS clause. 



Note: The required inclusion of the 
parameter DATE=YES in all input TPROCESS 
entries whose destination is a COBOL 
program results in the placing of the date 
and time of message entry in the input CD 
(see the section "Additional Interface 
Considerations" in the chapter entitled 
"Using the Teleprocessing Feature"). 



WORKING-STORAGE SECTION 



Separate Modules 



COMMUNICATION SECTION 



The Communication Section of a COBOL 
program must be specified if the program is 
to take advantage of the Teleprocessing 
Feature (TP). Through the inclusion of 
Communication Description (CD) entries, the 
programmer establishes communication 
between the COBOL object program and the 
Message Control Program (MCP). 



CD Entries 



When specified, the Communication 
Section must contain at least one CD entry. 
For example, a single CD entry would be 
sufficient for applications with either an 
input or an output message but not both. A 
COBOL TP program that is both to receive 
and to send messages must contain at least 
two 1 CD entries, as below. 

CD cd-name FOR INPUT. 
CD cd-name FOR OUTPUT. 

The CD entry may instead be pre-written 
and included in the user-created library. 
The programmer may then include the entry 
in a COBOL program by means of a COPY 
statement. 

CD cd-name COPY library-name. 

The input CD contains such information as 
input queue and sub-queue names, message 
date and time, the source, the message text 
length, the end key, the message status 
key, and the queue depth. The output CD 
contains the text length, a status key, an 
error key, and the name of the output 
queue. For information about the CD 
formats possible, see the publication IBM 
OS F ull America n Nat ional Sta n dar d CO BOL, 
Order No. GC28-6396. 



^Multiple input and output CD entries may 
be specified. 



In a large program, the programmer 
should plan ahead for breaking the programs 
into separately compiled modules, as 
follows: 

1. When employing separate modules, an 
attempt should be made to combine 
entries of each Working-Storage 
Section into a single level-01 record 
(or one level-01 record for each 32K 
bytes). Logical record areas can be 
indicated by use of level-02, level-03 
etc. , entries. A CALL statement with 
the USING option is more efficient 
when a single item is passed than when 
many level-01 and/or level-77 items 
are passed. When this method is 
employed, mistakes are more easily 
avoided. 

2. Areas that do not have VALUE clauses 
should be separated from areas that do 
need VALUE clauses. VALUE clauses 
(except for level- 88 items) are 
invalid in the Linkage Section and the 
Communication Section. 

3. When the Working-Storage Section is 
one level-01 item with no VALUE 
clauses, the COPY statement can easily 
be used to include the item as the 
description of a Linkage Section in a 
separately compiled module. 

4. See "Use of Segmentation Feature" for 
more information on how to modularize 
the Procedure Division of a COBOL 
program. 



Loca ting the Working-Storage Section in 
Dumps 



When any one or more of the options 
PMAP, CLIST, and DMAP are specified, both 
the location and the length (in 
hexadecimal) of the Working-Storage 
Section, if any, are provided (see the 
section "Options for the Compiler" in the 
chapter entitled "Job Control Procedures") 
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Alternatively, the programmer may locate 
this section in object-time dumps by 
including the following two statements in 
the program, in the order given: 

77 FILLER PICTURE X(44), VALUE "PROGRAM !// 
XXXXXXXX WORKING -STORAGE BEGINS HERE". 

01 FILLER PICTURE X(42), VALUE "PROGRAM 
XXXXXXXX WORKING-STORAGE ENDS HERE". 



different usage. This can be done with the 
REDEFINES clause as follows: 

01 PAYROLL-RECORD. 

05 EMPLOYEE- RECORD PICTURE X(28). 
05 EMPLOYEE-FIELD REDEFINES 

EMPLOYEE RECORD. 

10 NAME PICTURE X(23). 

10 NUMBERX PICTURE S9(5) COMP. 
05 DATE-RECORD PICTURE X<10). 



These two nonnumeric literals will 
appear in all dumps of the program, 
delineating the Working-Storage Section. 
The program-name specified in the 
PROGRAM-ID clause should replace the 
XXXXXXXX in the literal. 



DATA DESCRIPTION 



As an example of different data 
descriptions specified for the same data, 
the following illustrates how a table 
(TABLEA) can be initialized: 



05 VALUE- A. 

10 Al PICTURE S9(9) 

VALUE IS ZEROES. 
10 A2 PICTURE S9(9> 

VALUE IS 1. 



COMPUTATIONAL 



COMPUTATIONAL 



The Procedure Division operations that 
most often require adjustment of data items 
include the MOVE statement, the IF 
statement when used in a relation test, and 
arithmetic operations. Efficient use of 
data description clauses, such as 
REDEFINES, PICTURE, and USAGE, avoids the 
generation of extra code. 



REDEFINES Clause 



REUS I NG DATA AREAS : The main storage area 
can be used more efficiently by writing 
different data descriptions for the same 
data area. For example, the coding that 
follows shows how the same area can be used 
as a work area for the records of several 
input files that are not processed 
concurrently : 

WORKING- STORAGE SECTION. 
01 WORK-AREA-FILE1. 

(largest record description for FILED 



01 WORK-AREA-FILE2 REDEFINES 
WORK - AREA- F I LEI . 
(largest record description for FILE2) 



10 A100 PICTURE S9(9) 

COMPUTATIONAL VALUE IS 99. 

05 TABLEA REDEFINES VALUE- A 

PICTURE S9(9) COMPUTATIONAL 
OCCURS 100 TIMES. 

No te: Caution should be exercised when 
redefining a subscript; for if the value of 
the redefining data item is changed in the 
Procedure Division, no new calculation for 
the subscript is performed. 



PICTURE Clause 



DECIMAL- POINT_ALIGNMENT : Procedure 
Division operations are most efficient when 
the decimal positions of the data items 
involved are aligned. If they are not, the 
compiler generates instructions to align 
the decimal positions before any operations 
involving the data items can be executed. 
This is referred to as scaling. 

Assume, for example, that a program 
contains the following instructions : 

WORKING- STORAGE SECTION. 
77 A PICTURE S999V99. 
77 B PICTURE S99V9. 



ALTER NATE G ROUPINGS A ND D ESCRIPTIONS : 
Program data can often be described more 
efficiently by providing alternate 
groupings or data descriptions for the same 
data. For example, a program refers to 
both a field and its subfields, each of 
which is more efficiently described with a 



PROCEDURE DIVISION. 



ADD A TO B. 
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Time and internal storage space are 
saved by defining B as: 

77 B PICTURE S99V99. 

If it is inefficient to define B 
differently, a one-time conversion can be 
done, as explained in "Data Format 
Conversion, " 

FIELDS OF U NEQUAL LENGTH : When a data item 
is moved to another data item of a 
different length, the following should be 
considered: 

• If the items are external decimal 
items, the compiler generates 
instructions to insert zeros in the 
high-order positions of the receiving 
field when it is the larger. 

• If the items are nonnumeric, the 
compiler generates instructions to 
insert spaces in the low-order 
positions of the receiving field (or 
the high-order positions if the 
JUSTIFIED RIGHT clause is specified. 
This generation of extra instructions 
can be avoided if the sending field is 
described with a length equal to or 
greater than the receiving field. 

Use o f Sign : The absence or presence of a 
plus or minus sign in the description of an 
arithmetic field often can affect the 
efficiency of a program. The following 
paragraphs discuss some of the 
considerations. 

Decimal Items : The sign position in an 
internal or external decimal item can 
contain: 

1. A plus or minus sign. If S is 

specified in the PICTURE clause, a 
plus or minus sign is inserted when 
either of the following conditions 
prevails : 

a. The item is in the Working-Storage 
Section and a VALUE clause has 
been specified. 

b. A value for the item is assigned 
as a result of an arithmetic 
operation during execution of the 

program. 

If an external decimal item is 
punched, printed, or displayed, an 
overpunch will appear in the low-order 
digit. In EBCDIC, the configuration 
for low-order zeros normally is a 
nonprintable character. Low-order 
digits of positive values will be 
represented by one of the letters A 
through I (digits 1 through 9) ; 
low-order digits of negative values 



2. 



will be represented by one of the 
letters J through R (digits 1 through 
9). 



A hexadecimal F. If S is not 
specified in the PICTURE clause, an F 
is inserted in the sign position when 
either of following conditions exists! 



b. 



The item is in the Working-Storage 
Section and a VALUE clause has 
been specified. 

A value for the item is developed 
during the execution of the 
program. 



3. 



An F is treated as positive, but is 
not an overpunch. 

An invalid configuration. If an 
internal or external decimal item 
contains an invalid configuration in 
the sign position, and if the item is 
involved in a Procedure Division 
operation, the program will be 
abnormally terminated. 



Items for which no S has been specified 
(unsigned items) are treated as absolute 
values. Whenever a value (signed or 
unsigned) is stored in, or moved in an 
elementary move to an unsigned item, a 
hexadecimal F is stored in the sign 
position of the unsigned item. For 
example, if an arithmetic operation 
involves signed operands and an unsigned 
result field, compiler-generated code will 
insert an F in the sign position of the 
result field when the result is stored. 

For internal and external decimal items 
used as input, it is the user's 
responsibility to ensure that the input 
data is valid. The compiler does not 
generate a test to ensure that the 
configuration in the sign position is 
valid. 

When a group item is involved in a move, 
the data is moved without regard to the 
level structure of the group items 
involved. The possibility exists that the 
configuration in the sign position of a 
subordinate numeric item may be destroyed. 
Therefore, caution should be exercised in 
moves involving group items with 
subordinate numeric fields or with other 
group operations such as READ or ACCEPT. 



SIGN Clause 



This clause, which specifies both the 
position and the mode of the operational 
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siqn for a numeric data description entry, 
is required only when an explicit 
description of the sign's properties is 
necessary. The SIGN clause may be 
specified for either a numeric data 
description entry whose PICTURE contains 
the character S or a group item that 
contains at least one such numeric data 
description entry. 

The numeric data description entries to 
which the SIGN clause applies must be 
described, implicitly or explicitly, as 
USAGE IS DISPLAY. Only one SIGN clause ma^ 
be associated with any given numeric data 
description entry. 



as a separate character or not, as he 
chooses. If the SEPARATE CHARACTER option 
is specified: 



• The position of the character S is not 
taken to be a digit position. 



The character S is counted in 
determining tne size of the data item. 



TVt^ ,~.J-.-a-»-- 



:er: 



ire iicq^ f m 



the positive and the negative 
operational signs, respectively. 



The format of the SIGN clause is as 
follows: 

(leading I 
sign is < > [ separate character] 

(trailing) 



Use of the SEPARATE CHARA CTER Opt ion: The 
programmer can elect to consider the 
character S in the PICTURE character string 



• If neither the character ' +' nor the 
character '-' is present in the data at 
object time, an error takes place and 
the program ABENDS. 

Whether or not the SEPARATE CHARACIER 
option is in effect, the operational sign 
is assumed to be associated with either the 
LEADING or the TRAILING digit position, as 
specified, of the elementary numeric data 
item. 
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Table 25. Data Format Conversion 
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USAGE Clause 

This clause should be written at the 
highest level possible. 

DATA FORMAT CONVERSION : Operations 
involving mixed, elementary numeric data 
formats require conversion to a common 
format. This usually means that additional 
storage is used and execution time is 
increased. The code generated must often 
move data to an internal work area, perform 
any necessary conversion, and then execute 
the indicated operation. Often, too, the 
result may have to be converted in the same 
way (see Table 25) . 

If it is impractical to use the same 
data formats throughout a program, and if 
two data items of different formats are 
frequently used together, a one-time 
conversion can be effected. For example, 
if A is defined as a COMPUTATIONAL item and 
B as a COMPUTATIONAL- 3 item, A can be moved 
to a work area that has been defined as 
COMPUTATIONAL- 3. This move causes the data 
in A to be converted to COMPUTATIONAL- 3. 
Whenever A and B are used in a Procedure 
Division operation, reference can be made 
to the work area rather than to A. Using 
this technique, the conversion is performed 
only once, instead of each time an 
operation is performed. 

The following eight cases show how data 
conversions are handled on mixed elementary 
items for names, data comparisons, and 
arithmetic operations. Moves to and from 
group items, without the CORRESPONDING 
option, as well as comparisons involving 
group items, are done without conversion. 



To Perform Arithmetic Operat ions : 
Converts DISPLAY data to COMPUTATIONAL- 3 
or COMPUTATIONAL data. 



COMPUTATIONAL- 3 to COMPUTATIONAL : 

To Move Data : Moves COMPUTATIONAL- 3 
data to a work field and the converts 
COMPUTATIONAL- 3 data to COMPUTATIONAL 
data. 

To Co mp are Data: Converts COMPUTATIONAL 
data to COMPUTATIONAL- 3 or vice versa, 
depending on the size of the field. 

To Perform Arithmetic Op erations : 
Converts COMPUTATIONAL data to 
COMPUTATIONAL- 3 or vice versa, depending 
on the size of the field. 



COMPUTATIONAL to COMPUTATIONAL- 3 : 

To Move Data: Converts COMPUTATIONAL 
data to C0MPUTATI0NAL-3 data in a work 
field, then moves the work field. 

To Compare Data: Converts COMPUTATIONAL 
to COMPUTATIONAL- 3 data or vice versa, 
depending on the size of the field. 

To Preform Arithmetic Opera tions : 
Converts COMPUTATIONAL to 
COMPUTATIONAL- 3 data or vice versa, 
depending on the size of the field. 



COMPUTATIONAL to Numeric DISPLAY: 



To Move Data : Converts COMPUTATIONAL 
data to COMPUTATIONAL- 3 data and then to 
DISPLAY data. 



Nume ric DISPLAY to COMPUTATIONAL- 3 : 

To Move Data : Converts DISPLAY data to 
COMPUTATIONAL- 3 data. 

To Compare Data : Converts DISPLAY data 
to COMPUTATIONAL- 3 data. 

T o Perform Arithmetic Operation s : 
Converts DISPLAY data to COMPUTATIONAL-3 
data. 



Numeric DISPLAY to COMPUTATIONAL: 



To Compare Data : Converts DISPLAY to 
COMPUTATIONAL or both COMPUTATIONAL and 
DISPLAY data to COMPUTATIONAL-3 data, 
depending on the size of the field. 

To Perform Arithmetic Ope rations : 
Depending on the size of the field, 
converts DISPLAY data to COMPUTATIONAL 
data, or both DISPLAY and COMPUTATIONAL 
data to COMPUTATIONAL-3 data in which 
case the result is generated in a 
COMPUTATIONAL-3 work area and then 
converted and moved to the DISPLAY 
result field. 



T o Mo ve Data : Converts DISPLAY data to 
COMPUTATIONAL-3 data and then to 
COMPUTATIONAL data. 

T o Compare Data : Converts DISPLAY to 
COMPUTATIONAL-3 and then to 
COMPUTATIONAL or converts both DISPLAY 
and COMPUTATIONAL data to 
COMPUTATIONAL-3 data. 



COMPU TATIONAL-3 to Numeric DISPLAY : 

To Mo ve Data: Converts COMPUTATIONAL-3 
data to DISPLAY data. 

To Compare Data: Converts DISPLAY data 
to COMPUTATIONAL-3 data. The result is 
generated in a COMPUTATIONAL-3 work area 
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and is then converted and moved to the 
DISPLAY result field. 



Special Considerations for DISPLAY and 
COMPUTATIONAL Fields 



Numeric DISPLAY to Numeric DISPLAY: 



T o Perform Arithmetic Ope rations : 
Converts all DISPLAY data to 
t^oKPtrTATxOtrAir-lrndax^r^ — "rrre - resnrt~is" 
generated in a COMPUTATIONAL- 3 work area 
and is then converted to DISPLAY and 
moved to the DISPLAY result field. 



External Floating-Point to Any Ot her: When 
an external floating-point item is to be 
used in an airthmetic operation or in data 
manipulation, precision errors may occur 
due to required conversions. 



Intern al Floating - Point to Any Ot her: When 
an item described as COMPUTATIONAL- 1 or 
COMPUTATIONAL- 2 (internal floating-point) 
is used in an operation with another data 
format, the item in the other data format 
is always converted to internal 
floating-point. If necessary, the internal 
floating-point result is then converted to 
the format of the other data item. 



SYNCHRONIZED Clause 



DATA FORMATS : As shown in Table 24, 
COMPUTATIONAL, COMPUTATIONAL- 1, and 
COMPUTATIONAL- 2 items have specific 
boundary alignment requirements. To ensure 
correct alignment, either the programmer or 
the compiler may have to add slack bytes, 
or the compiler must generate instructions 
to move the item to a correctly aligned 
work area when reference is made to the 
item. 

The SYNCHRONIZED clause may be used at 
the elementary level to specify the 
automatic alignment of elementary items on 
their proper boundaries or at level-01 to 
synchronize all elementary items within the 
group. For COMPUTATIONAL items, if the 
PICTURE is in the range of S9 through 
S9(4), the item is aligned on a half word 
boundary. If the PICTURE is in the range 
of S9(5) through S9(18), the item is 
aligned on a fullword boundary. For 
C0MPUTATI0NAL-1 items, the item is aligned 
on a fullword boundary. For 
COMPUTATIONAL- 2 items, the item is aligned 
on a double-word boundary. The 
SYNCHRONIZED clause and slack bytes are 
fully discussed in the publication IBM_OS 
Full American National Standard COBOL. 



NUMERIC DISPLAY FIEL DS: Zeros are not 
inserted into numeric DISPLAY fields by the 
instruction set. When numeric DISPLAY data 
is moved, the compiler generates 
instructions that insert any necessary 
"zeros' into "the ~D~rSPLAY"r ieldsT "when" 
numeric DISPLAY data is compared, and one 
field is smaller than the other, the 
compiler generates instructions to move the 
smaller item to a work area where zeros are 
inserted. 

COMP UTATIONAL FIELDS : COMPUTATIONAL fields 
can be aligned on either a halfword or 
fullword boundary. If an operation 
involves COMPUTATIONAL fields of different 
lengths, the halfword field is 
automatically expanded to a fullword field. 
Therefore, mixed halfword and fullword 
fields require no additional operations. 

COMP UTA TIONAL- 1 AND COMPUT AT IONAL- 2 FIELDS : 
If an arithmetic operation involves a 
mixture of short-precision and 
long-precision fields, the compiler 
generates instructions to expand the 
short-precision field to a long-precision 
field before the operation is executed. 

COMPUTATIONAL- 3_FIELDS : The compiler does 
not have to generate instructions to insert 
high-order zeros for ADD and SUBTRACT 
statements that involve COMPUTATIONAL-3 
data. The zeros are inserted by the 
instruction set. 



Data Formats in the Computer 



The various COBOL data formats and how 
they appear in the computer in EBCDIC 
(Extended Binary-Coded-Decimal Interchange 
Code) format are illustrated by the 
following examples. More detailed 
information about these data formats 
appears in the publication IB M OS 
Principles of Operation ! Order 
No. A22-6821. 

Numeri c DI S PLAY (External Decimal) : 
Suppose the value of an item is -1234, and 
the PICTURE and USAGE are: 

PICTURE 9999 DISPLAY. 



or 



PICTURE S9999 DISPLAY. 

The item appears in the computer in the 
following forms respectively: 
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I Fl | F2 | F3 | F4 | 
L X X X J 

Byte 

| Fl | F2 | F3 | D4 | 
L X X X J 

Byte 

Hexadecimal ■ F is- treated arithmetically as 
plus in the low-order byte. The 
hexadecimal character D represents a 
negative sign. 



COMPU TATIONAL- 3 (Int e rnal D ecimal) : 
Suppose the value of an item is +1234, and 
its PICTURE and USAGE are: 



PICTURE 9999 COMPUTATIONAL- 3. 

or 
PICTURE S9999 COMPUTATIONAL- 3. 



The item appears in the computer in the 
following forms, respectively: 

| 01 | 23 | 4F | 

L X X J 

Byte 

| 01 | 23 | 4C | 
i x x J 

Byte 

Hexadecimal F is treated arithmetically as 
positive. Tji^_hej c a^ e€ ± m -aJL character-. C 
represents a plus sign. ' 

N ote : Since the low-order byte of an 
internal decimal number always contains a 
sign field, an item with an odd number of 
digits can be stored more efficiently than 
an item with an even number of digits. 
Note that a leading zero is inserted in the 
foregoing example. 



C OMP U TATIONAL (Bi n ary) : Suppose the value 
of an item is 1234, and its PICTURE and 
USA3E are: 

PICTURE S9999 COMPUTATIONAL. 

The item appears in the computer in the 
following form: 

| 0000 | 0100 | 1101 | 0010 | 
l x x x J 

.t 

sign 
position 



A 0-bit in the sign position means the 
number is positive. Negative numbers are 
represented in two* s complement form; thus, 
the sign position of a negative number will 
always contain a 1-bit. 

For example -1234 would appear as 
follows: 



| 1111 | 1011 | 0010 | 1110 | 

L X X X J 



sign 
position 



Binary Item Manipulation: A binary item is 
allocated storage ranging from one halfword 
to two words, depending on the number of 9s 
in its PICTURE. Table 26 is an 
illustration of how the compiler allocates 
this storage. Note that it is possible for 
a value larger than that implied by the 
PICTURE to be stored in the item. For 
example, PICTURE S9(4) implies a maximum 
value of 9,999, although it could actually 
hold the number 32,767. 

Because most binary items are 
manipulated according to their allotted 
storage capacity, the programmer can ignore 
this situation. For the following reasons, 
however, there are some cases where he must 
be careful of his data: 

1. When the ON SIZE ERROR option is used, 
the size test is made on the basis of 
the maximum value allowed by the 
picture of the result field. If a 
size error condition exists, the value 
of the result field is not altered and 
control is given to the imperative 
statements specified by the error 
option. 

2. When a binary item is displayed or 
exhibited, the value used is a 
function of the number of 9s specified 
in the PICTURE clause. 

3. When the actual value of a positive 
number is significantly larger than 
its picture value, a 1 could result in 
the sign position of the item, causing 
the item to be treated as a negative 
number in subsequent operations. 

Table 27 illustrates three binary 
manipulations. In each case, the result 
field is an item described as PICTURE S9 
COMPUTATIONAL. One halfword of storage has 
been allocated; and no ON SIZE ERROR option 
is involved. Note that if the ON SIZE 
ERROR option had been specified, it would 
have been executed for cases B and C. 
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xabie 26. Relationship ot PICTURE to Storage Allocation 



PICTURE 



j. 

| S9 through S9(4) 



Maximum Working Value | 



Assigned Storage 



32,767 1 one half word 

I 

2,147, 483, 647 | one fullword 



|S9(5) through S9(9) | 

! ! ! 

|S9(10) through S9(18) j 9,223,372,036,854,775,807 1 two fullwords 



Table 27. Treatment of Varying Values in a Data Item of PICTURE S9 
r" 



Case 


1 

1 
_ i 


Hexadecimal Result of 
Binary Calculation 


1 

1 
1 


Decimal 
Equivalent 


1 

1 
1 


Actual Decimal 
in Halfword of 


Value 
Storage 


1 

1 
1 


Display or 
Exhibit Value 


1 


A 


T 

1 
_ 1 




0008 


1 
1 


8 


T 

1 
1 






+ 8 




1 
1 


8 


1 


B 


T 

1 
1 




000A 


1 
1 


10 


1 






+ 10 




1 
1 





1 


C 


1 
1 




C350 


T 

1 
1 


50000 


T 

1 
i .. 






-15536 




1 

1 
i 


6 





C OMP U TATIONAL- 1 or COMPUTATIONA L- 2 
(Floa ting Point) : Suppose the value of an 
item is +1234, and that its USAGE is 
COMPUTATIONAL- 1, the item appears in the 
computer in the following form: 



| | 100 0011|0100 1101 0010 0000 0000 ooooi 

L_X J. J 

S 1 7 8 31 



PROCEDURE DIVISION 



A program can often be made more 
efficient or easier to debug in the 
Procedure Division with some of the 
techniques described below. 



MODULARIZING THE PROCEDURE DIVISION 



S is the sign position of the number. 



A 0-bit in the sign position indicates 
that the sign is plus. 

A 1-bit in the sign position indicates 
that the sign is minus. 

Bits 1 through 7 are the exponent 
(characteristic) of the number. 

Bits 8 through 31 are the fraction 
(mantissa) of the number. 



When the Procedure Divi 
modularized, programs are 
maintain and document. In 
modularization makes it si 
down a program using the s 
feature, thereby resulting 
efficient segmented progra 
Modularization of the Proc 
involves organizing it int 
functional levels: a main 
processing subroutines, an 
subroutines. 



sion is 
easier to 

addition, 
mple to break 
egmentation 

in a more 
m. 

edure Division 
o at least three 
-line routine, 
d input/output 



This form of data is referred to as 
floating-point. The example illustrates 
short-precision floating-point data 
( COMPUTATIONAL- 1) . In lonq-precision 
(COMPUTATIONAL- 2) , tne fraction length is 
56 bits. (For a detailed explanation of 
floating-point representation, see the 
publication IBM OS Principles of 
O per ation. ) 



Main-Line Routine 



This routine should be short, simple, 
and contain all the major logical decision: 
of the program. This routine controls 
which second-level subroutines are execute; 
and in what order. All second-level 
subroutines should be invoked from tne 
main-line routine by PERFORM statements. 
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Processi ng S ubroutines 



Intermediate Results and Binar y Data Items 



These should be broken down into as many 
functional levels as necessary, depending 
on the complexity of the program. These 
must be completely closed subroutines, with 
one entry point and one exit point. The 
entry point should be the first statement 
of the subroutine. The exit point should 
be the EXIT statement. The processing 
subroutines can perform only lower level 
subroutines; return to the higher level 
subroutine (processing subroutine) must be 
made by a GO TO statement, which references 
the EXIT statement. 



If an operation involving binary 
operands requires an intermediate result 
greater than 18 digits, the compiler 
converts the operands to internal decimal 
before performing the operation. If the 
result field is binary, the result will be 
converted from internal decimal to binary. 

If an intermediate result will not be 
greater than nine digits, the operation is 
performed most efficiently on binary data 

-LXCX-IO. 



Input/ Output Subrout i nes 



These should be the lowest level 
subroutines, since all higher level 
subroutines should have access to them. 
There should be one OPEN subroutine and one 
CLOSE subroutine for the program, and only 
one functional (READ or WRITE) subroutine 
for each file. One READ or WRITE 
subroutine per file, which is always 
performed, has several advantages: 



1. Coding can be added to count records 
on a file, transform blanks into 
zeros, check for 9s padding, etc. 

2. Input and output files can be 
reformatted without changing the logic 
of the program. 

3. DEBUG statements can be added during 
testing to create input or to DISPLAY 
formatted output, instead of having to 
create a test file. 



Illtermediate_Results_and_COBOL_Library 
Subroutines 



If a decimal multiplication operation 
requires an intermediate result greater 
than 30 digits, a COBOL library subroutine 
is used to perform the multiplication. Ihe 
result of this multiplication is then 
truncated to 30 digits. 

A COBOL library subroutine is used to 
perform division if: 

1. the scaled divisor is equal to or 
greater than 15 digits. 

2. the length of the scaled divisor plus 
the length of the scaled dividend is 
greater than 16 bytes. The lengths of 
the operands are internal decimal. 

3. the scal ed dividend is greater than 30 
digits. (A scaled dividend is a 
number that has been multiplied by a 
power of ten in order to obtain the 
desired number of decimal places in 
the quotient. ) 



Intermed iate Resu lts Gre at er t han 30 Digits 



INTERMEDIATE RESULTS 



The compiler treats arithmetic 
statements as a succession of operations 
and sets up intermediate result fields to 
contain the results of these operations. 
Examples of such statements are the 
arithmetic statements, and statements 
containing arithmetic expressions. In the 
publication IBM O S Fu l l American National 
Standard COBOL , the section "Appendix A: 
Intermediate Results" describes the 
algorithms used by the compiler to 
determine the number of places reserved for 
intermediate result fields. 



Whenever the number of digits in a 
decimal intermediate result is greater than 
30, the field is truncated to 30 digits. A 
warning message will be generated at 
compile time, and program flow will not be 
interrupted at execution time. This 
truncation may cause a result to be 
incorrect. 

If binary or internal decimal data is in 
accord with its data description, no 
interrupt can occur because of an overflow 
condition in an intermediate result. This 
is due to the truncation described in the 
preceding paragraph. 
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if the possibility exists that an 
intermediate result field may exceed 30 
digits, truncation can be avoided by the 
specification of floating-point operands 
< COMPUTATIONAL- 1 or COMPUTATIONAL-2 ) ; 
however, accuracy may not be maintained. 



•i n1^ innigd±a^ e"'Kg5Qlt:5" :'an cr' , Plo atinq-Poxht' 
Data Items 



CANCEL Statement 



The CANCEL statement permits dynamic 
deletion of COBOL subprograms from tne 
COBOL processing environment. That is, a 
CANCEL statement issued for a subprogram 

T.ila^ n3£j DCCn a^nuuu.v,uj.j.^ iuaucu oauoct> L-IIt^ 

storage occupied by the subprogram to be 
freed. As a result, a suosequent call to 
tfie''su^pY6gram'''f'uhc'tidris' as if it were the 
first. 



If a floating-point operand has an 
intermediate result field in which exponent 
overflow occurs, the job will be abnormally 
terminated. 



CANCEL CALLED- PROGRAM. 

Note: A program other than the original 
caller may issue a CANCEL statement 
referring to a called program. 



Intermediate Results and the ON SIZE ER ROR 
Option 



The ON SIZE ERROR option applies only to 
the final calculated results and not to 
intermediate result fields. 



CLOSE Statement 



There are two ways in which tc use the 
CLOSE statement when closing several files: 

CLOSE DETAIL-FILE MASTER-FILE. 



or 



VERBS 



CLOSE DETAIL-FILE. 
CLOSE MASTER-FILE. 



CALL Statement 



The CALL statement permits communication 
between a COBOL object program and one or 
more COBOL subprograms or other language 
subprograms, A called program may be 
entered either at the beginning of the 
Procedure Division or later in the program. 
When a subprogram is called, it may already 
be core resident and be link-edited with 
the main program, or it may be specified as 
dynamic and link-edited into a separate 
load module. Dynamic loading, via the CALL 
statement, enables the user to load a 
subprogram only when it is actually needed. 

The first dynamic call to a subprogram 
brings in a fresh copy of that subprogram. 
Any subsequent calls to the same 
subprogram, by either the original caller 
or another subprogram in the same 
region/partition, cause a branch to the 
same copy of the subprogram in its 
last-used state, until the user deletes it 
(see the section on the "CANCEL 
Statement") . 



Each CLOSE statement for a file requires 
the use of a storage area that is directly 
proportional to the number of files being 
closed. Closing more than one file with 
the same statement is faster than when 
using a separate statement for each file. 
However, separate statements require less 
storage. 



COMPUTE Statement 



The use of the COMPUTE statement 
generates more efficient coding than does 
the use of individual arithmetic statements 
because the compiler can keep track of 
internal work areas and does not have to 
store the results of intermediate 
calculations. It is the user' s 
responsibility, however, to insure that the 
data is defined with the level of 
significance required in the answer. 



IF Statement 



For examples of both static and dynamic 
CALL statements, see the section "Dynamic 
Subprogram Considerations" in the chapter 
entitled "Calling and Called Programs." 



Nested and compound IF statements should 
be avoided as the logic is difficult to 
debug. 
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Performing an IF operation for an item 
greater than 256 bytes in length requires 
the generation of more instructions than 
are required for that of an IF operation 
for an item of 256 bytes or less. 



Note : In teleprocessing applications, the 
MESSAGE condition determines whether or not 
one or more complete messages exist in a 
designated queue of messages. The COBOL 
programmer can include in an IF statement 
the condition: 

[NOT] MESSAGE FOR cd-name 

with an action to be performed when the 
condition is met. 

When using compound IF statements, care 
must be taken to ensure that the message 
condition is tested, so that the QUEUE 
DEPTH field is actually updated. For 
example, according to the statement: 

IF A = B AND MESSAGE FOR QUEUE-IN. . . . 

then when A is not equal to B, the message 
condition is not tested and the QUEUE DEPTH 
field for QUEUE-IN is not updated. (For 
further discussion of the message 
condition, see the publication IBM OS Full 
American National Standard COBOL. ) 



MOVE Statement 



Performing a MOVE operation for an item 
qreater than 256 bytes in length requires 
the generation of more instructions than 
are required for that of a MOVE operation 
for an item of 256 bytes or less. 

When a MOVE statement with the 
CORRESPONDING option is executed, data 
items are considered CORRESPONDING only if 
their respective data names are the same, 
including all implied qualification, up to, 
but not including, the data-names used in 
the MOVE statement itself. 



For example, 

01 AA 

05 BB 

10 CC 
10 DD 

05 EE 

10 FF 



01 



XX 






05 


BB 






10 


CC 




10 


DD 


05 


YY 






10 


FF 



Note: The other rules for MOVE 
CORRESPONDING, of course, must still be 
satisfied. 



NOTE Statement 



An asterisk <*) should be used in place 
of the NOTE statement, because there is the 
possibility that when NOTE is the first 
sentence in a paragraph, it will 
inadvertently cause the whole paragraph to 
be treated as part of the NOTE. 



OPEN Statement 



There are two ways in which to use the 
OPEN statement when opening several files: 

OPEN INPUT INFILE UPDATES OUTPUT OUTFILE 

or 

OPEN INPUT INFILE 
OPEN INPUT UPDATES 
OPEN OUTPUT OUTFILE 



Each OPEN statement for a file requires 
the use of a storage area that is directly 
proportional to the number of files being 
opened. Opening more than one file with 
the same statement is faster than using a 
separate statement for each file. However, 
separate statements require less storage. 



PERFORM Verb 



PERFORM is a useful verb if the 
programmer adheres to the following rules: 

1. Always execute the last statement of a 
series of routines Deing operated on 
by a PERFORM statement. When 
branching out of the routine, make 
sure control will eventually return to 
the last statement of the routine. 
This statement should be an EXIT 
statement. Although no code is 
generated, the EXIT statement allows a 
programmer to recognize immediately 
the extent of a series of routines 
within the range of a PERFORM 
statement. 



The statement MOVE CORRESPONDING AA TO XX 
will result in moving CC and DD but not FF 
because FF of EE does not correspond to FF 
of YY). 



2. Always either PERFORM routine-name 
THRU routine-name-exit, or PERFORM 
section- name. A PERFORM 
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paragraph-name can cause trouble for 
the programmer trying to maintain the 
program. For example, if a paragraph 
must be broken into two paragraphs, 
the programmer must examine every 
statement to determine whether or not 
this paragraph is within the range of 
the PERFORM statement. Then all 
statements referencing the 
paja,gxa.pJ^rtaine_--in!ist be chaiigedL.to 
PERFORM THRU statements. 



READ INTO and WRITE FROM Options 



Use READ INTO and WRITE FROM, and do all 
processing in the Working-Storage Section. 
This is suggested for two reasons: 

1. Debugging is much simpler. 
Working-Storage areas are easier to 
locate in a dump than are buffer 
areas. And, if files are blocked, it 
is much easier to determine which 
record in a block was being processed 
when the abnormal termination 
occurred. 

2. Trying to access a record area after 
the AT END condition has occurred (for 
example, AT END MOVE HIGH-VALUE TO 
INPUT-RECORD) can cause problems if 
the record area is only in the File 
Section. 

Note : The programmer should be aware that 
additional time is used to execute the move 
operation involved in each READ INTO or 
WRITE FROM instruction. 



message control program (MCP) . The 
following example of the SEND statement is 
taken from the sample COBOL teleprocessing 
program shown in Figure 113: 

SEND CDNAME-OUT FROM IDENT-SEND WITH EMI. 



Notes : 



Al though. . the. C QBOL pro gram has acces s 
to a message only when the MCP has 
received it in entirety and placed it 
in a queue, once several messages have 
met this requirement the COBOL program 
can process messages from different MCP 
queues at the same time. 

If one execution of a RECEIVE statement 
(or a SEND statement) transmits only 
part of a message, subsequent 
executions of RECEIVE statements (or 
SEND statements) in that run unit are 
required for transmission of the rest 
of the message. 



START Statement 



The START statement must be executed 
before the READ statement for a given 
record if either of the following is true: 

• Processing begins with other than the 
first record; 

• Processing continues with a record 
other than the next sequential record. 



RECEIVE Statement 



There are two ways to use the START 
statement to begin processing a segment of 
a sequentially accessed indexed file at a 
specified key. The programmer may indicate 
either Method 1, to begin at a specific 
NOMINAL KEY that matches a RECORD KEY 
within the file, or Method 2, to start 
The RECEIVE statement makes available to within the first record in a specific 

the COBOL program a message, a message generic key class. 

segment, or part of a message or message 

segment, as well as information about that Method_l: 

message from a queue maintained by the 

message control program (MCP). The START file-name 

following example of the RECEIVE statement [ INVALID KEY imperative-statement] 

is taken from the sample COBOL 

teleprocessing program shown in Figure 114: 

RECEIVE CDNAME-IN MESSAGE INTO IDENT-REC. Method_2: 

START file-name USING KEY data-name 
EQ UAL TCfi 
SEND Statement J > identifier 



Specification of the SEND statement in 
the COBOL program causes a message, a 
message segment, or part of a message or 
message segment to be released to the 



[INVALID KEY imperative- statement] 

where data-name is the data-name given in 
the RECORD KEY clause and identifier 
contains the generic key value for the 
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request and may be any data item whose 
length is less than or equal to that of the 
RECORD KEY. 

N ote : For ISAM a problem may result with 
the generic key facility with binary key if 
the low-order byte of the search argument 
is binary zero. 



TRANSFORM Statement 



The TRANSFORM statement generates more 
efficient code than the EXAMINE statement 
with the REPLACING BY option when only one 
character is being transformed. TRANSFORM, 
however, uses a 256-byte table. 



STRING Statement 



UNSTRING Statement 



The STRING statement combines two or 
more subfields into a single field. When The UNSTRING statement separates 

this statement is executed, characters from contiguous data in a sending field, placing 

the sending item(s) are transferred to the it in multiple receiving fields. Ihe 

receiving item in the same way that moves example in Figure 68 illustrates the use of 

from alphanumeric to alphanumeric item(s) the UNSTRING statement options available to 

are effected. The example in Figure 66 the user, 
illustrates the use of the STRING statement 

options available to the user. For a For a discussion of the formats possible 

discussion of the formats possible with the with the UNSTRING statement, see the 

STRING statement, see the publication OS publication IBM_OS_Full_American_National 

Full American Nationa l S tandard COBOL. §tandard_COBOL. 

r 1 

STRING SNDFLD5 DELIMITED BY DLMTR 
SNDFLD6 DELIMITED BY SIZE 



combine data in SNDFLD5 up to the delimiter indicated by DLMTR with all the data 
in another sending field (as indicated by the SIZE option of the STRING 
statement) . 

INTO RCDFLD1 WITH POINTER POINTR 

Place the result in RCDFLDl beginning at the relative location designated 
by POINTR. 

ON OVERFLOW GO TO 0VERFL0W2. 

If RCDFLDl is not large enough to accommodate the combined data-fields, or 
if the original contents of the pointer field were less than 1, execute a user- 
written checking routine called 0VERFL0W2. 



Figure 67. Using the STRING Statement 
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UNSTRING SNDFLD 

Separate the data in the sending area. 

DELIMITED BY DLMTR1 

OR SPACES 

OR ALL * E* 
INTO RCFLD 



When the character, or set of characters, marking the end of a section of the 
sending area is found, move the isolated data into the data-receiving field. 

DELIMITER IN DELIM-IN 

Move the delimiter found into the delimiter-receiving area DELIM-IN. 

COUNT IN COUNT- IN 

Specify in COUNT-IN the number of characters placed in the RCFLD 
data-receiving field. 

WITH POINTER POUNTR 

Indicate the relative position in the SNDFLD sending area of the first 

character to be examined. At the end of the operation, POINTR contains a value 

equal to the initial value plus the number of characters examined in the sending 
field. 

TALLYING IN TALLY-IN 

Record the number of data-receiving areas acted upon. At the end of the 
operation, TALLY-IN will contain a value equal to the initial value plus the 
number of receiving areas acted upon. 

ON OVERFLOW 

DISPLAY 'OVERFLOW CONDITION' 
GO TO CHECK-ROUTINE. 

If the data-receiving fields cannot accommodate the data being sent, or if 

the original value of the pointer was less than 1 or greater than the size of the 

sending field, execute a user-written checking routine. 



Figure 68. Using the UNSTRING Statement 



USING THE REPORT WRITER FEATURE 



REPORT Clause in FD 



A given report-nam e may appear in a 
maximum of two file description entries. 
The file description entries need not have 
the same characteristics. If the same 
report-name is specified in two file 
description entries, the report will be 
written on both files. For example: 



DATA DIVISION. 

FD FILE-1 RECORDING MODE F 

RECORD CONTAINS 121 CHARACIEkS 

REPORT IS REPORT-A. 
FD FILE- 2 RECORDING MODE V 

RECORD CONTAINS 101 CHARACTERS 

REPORT IS REPORT-A. 



For each GENERATE statement, the records 
for REPORT-A will be written on FILE-1 and 
FILE-2, respectively. The records on 
FILE-2 will not contain columns 102 through 
121 of the corresponding records on FILE-1. 



ENVIRONMENT DIVISION. 

SELECT FILE-1 ASSIGN UR-1403-S-PRTOUT. 
SELECT FILE-2 ASSIGN UT-2U00-S-SYSUT1. 



Summing Techni que 



The object program can be made more 
efficient with respect to execution time by 
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keeping in mind the fact that Report Writer 
source coding is treated as though the 
programmer had written the program in COBOL 
without the Report Writer feature. 
Therefore, a complex source statement or 
series of statements will generally be 
executed faster than simple statements that 
perform the same function. The example 
below shows two coding techniques for the 
Report Section of the Data Division. 
Method 2 uses the more complex statements. 



FILE SECTION. 



05 NO- PURCHASES 



PICTURE 99. 



REPORT SECTION. 

01 DETAIL-1 TYPE DETAIL. 

05 COLUMN 30 PICTURE 99 SOURCi 

NO-PURCHASES. 



RD. . . CONTROLS AK±; YiiAR MONTH WEEK DAYY 
Method 1: 



01 DETAIL- 2 TYPE DETAIL. 



01 TYPE CONTROL FOOTING YEAR. 

05 SUM COST. 
01 TYPE CONTROL FOOTING MONTH. 

05 SUM COST. 
01 TYPE CONTROL FOOTING WEEK. 

05 SUM COST. 
01 TYPE CONTROL FOOTING DAYY. 

05 SUM COST. 



01 DAY TYPE CONTROL FOOTING 
LINE PLUS 2. 



05 



SUBTOTAL COLUMN 30 PICTURE 999 
SUM NO-PURCHASES. 



Method 2: 



01 TYPE CONTROL FOOTING YEAR. 

05 SUM A. 
01 TYPE CONTROL FOOTING MONTH. 

05 A SUM B. 
01 TYPE CONTROL FOOTING WEEK. 

05 B SUM C. 
01 TYPE CONTROL FOOTING DAYY. 

05 C SUM COST. 

Method 2 will execute faster. One addition 
will be performed for each day, one more 
for each week, and one for each month. In 
Method 1, four additions will be performed 
for each day. 



Use of SUM 



Unless each identifier is the name of a 
SUM counter in a TYPE CONTROL FOOTING 
report group at an equal or lower position 
in the control hierarchy, the identifier 
must be defined in the File, 
Working- Storage or Linkage Sections, as 
well as in a TYPE DETAIL report group as a 
SOURCE item. A SUM counter is 
algebraically incremented just before 
presentation of the TYPE DETAIL report 
group in which the item being summed 
appears as a source item or the item being 
summed appeared in a SUM clause that 
contained an UPON option for this DETAIL 
report group. This is known as SOURCE- SUM 
correlation . In the following example, 
SUBTOTAL is incremented only when DETAIL-1 
is generated: 



01 MONTH TYPE CONTROL FOOTING 
LINE PLUS 2 NEXT GROUP 
NEXT PAGE. 



SUM Routines 



A SUM routine is generated by the Report 
Writer for each DETAIL report group of the 
report. The operands included for summing 
are determined as follows: 

1. The SUM operand(s) also appears in a 
SOURCE clause (s) for the DETAIL report 
group. 

2. The UPON detail-name option was 
specified in the SUM clause. In this 
case, all the operands are included in 
the SUM routine for only that DETAIL 
report group, even if the operand 
appears in a SOURCE clause in other 
DETAIL report groups. 



When a GENERATE detail-name statement is 
executed, the SUM routine for that DETAIL 
report group is executed in its logical 
sequence. When a GENERATE report-name 
statement is executed and the report 
contains more than one DETAIL report group, 
the SUM routine is executed for each one. 
The SUM routines are executed in the 
sequence in which the DETAIL report groups 
are specified. 

The following examples show the SUM 
routines that are generated by the Report 
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Writer. Example 1 illustrates how operands 
are selected for inclusion in the routine 
on the basis of simple SOURCE-SUM 
correlation. Example 2 illustrates how 
operands are selected when the UPON 
detail-name option is specified. 



EXA MPLE 1 : The following statements are 
coded in the Report Section: 

01 DETAIL-1 TYPE DE. . . 
05 ... SOURCE A. 



01 TYPE CF. . . 

05 SUM-CTR-1.. .SUM A, B, 
DETAIL- 2. 



C UPON 



The following SUM routines would then oe 
generated instead of those resulting from 
the calculations in Example 1. 



SUM Routine for DETAIL-1 



REPORT- SAVE 
REPORT-RETURN 



01 DETAIL-2 TYPE DE. . . 
05 . . . SOURCE B. 
05 ... SOURCE C. 



01 DETAIL-3 TYPE DE. . . 
05 SOURCE B. 



SUM_Routine_for_DETAIL-2 

REPORT-SAVE 

ADD A TO SUM-CTR-1. 

ADD B TO SUM-CTR-1. 

ADD C TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT-RETURN 



SUM Routine for DETAIL-3 



01 TYPE CF. . . 

05 SUM-CTR-1. . .SUM A, B, C. 



RE PORT- SAVE 

ADD B TO SUM-CTR-2, 
REPORT- RETURN 



01 TYPE CF 

05 SUM-CTR-2... SUM B. 



One SUM routine is generated for each 
DETAIL report group, as follows: 

SUM Routine for DET AIL-1 

REPORT-SAVE 

ADD A TO SUM-CTR-1. 
REPORT- RETURN 



Output L ine Overlay 



The Report Writer output line is put 
together with an internal REDEFINES 
specification, indexed by in teger-1 . No 
check is made to prevent overlay on any 
line. For example: 



SUM R outine for D ETAIL-2 

REPORT-SAVE 

ADD B TO SUM-CTR-1. 

ADD C TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT- RETURN 

SUM Routine for DETAIL-3 



05 COLUMN 10 PICTURE X(23) 

VALUE "MONTHLY SUPPLIES REPORT". 

05 COLUMN 12 PICTURE Xt9> 

SOURCE CURRENT-MONTH. 

the length of 23 in column 10, followed by 
a specification for column 12 will cause 
field overlay. 



REPORT- SAVE 

ADD B TO SUM-CTR-1. 

ADD B TO SUM-CTR-2. 
REPORT-RETURN 



E§.9L§_Breaks 



E XAM PLE 2: In this example, the same 
coding is used as in Example 1, with one 
exception: the UPON detail-name option is 
used for SUM-CTR-1, as follows: 



The Report Writer page break routine 
operates independently of the routines that 
are executed after any control breaks 
(except that a page break will occur as the 
result of a LINE NEXT PAGE clause). Thus, 
the programmer should be aware of the 
following facts: 
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1. A Control Heading is not printed after 
a Page Heading except for first 
generation. If the programmer wishes 
to have the equivalent of a Control 
Heading at the top of each page, he 
must include the information and data 
to be printed as part of the Page 
Heading. But since only one Page 
Heading may be specified for each 
report, he should be selective in 
considering his Control Heading 
because this "Control Heading" will be 
the same for each page, and may be 
printed at inopportune times (see 
"Control Footings and Page Format, " in 
this chapter. ) 



WITH CODE Clause 



When more than one report is being 
written on a file and the reports are to be 
selectively written, a unique 1-character 
code must be given for each report. h 
mnemonic-name is specified in the RD-level 
entry for each report and is associated 
with the code in the Special-Names 
paragraph of the Environment Division. 



Note: If a report is written with the CODE 
option, the report should not be written 
directly to a printer device. 



2. GROUP INDICATE items are printed after 

page and control breaks. Figure 69 

contains a GROUP INDICATE clause and 
shows the execution output. 



This code will be written as the first 
character of each record that is written on 
the file. When the programmer wishes to 
write a report from this file, he needs 
merely to read a record, check the first 
character for the desired code, and have it 
printed if this code is found. The record 
should be printed starting from the third 
character, as illustrated in Figure 70. 



REPORT SECTION. 



01 DETAIL-LINE TYPE IS DETAIL LINE 

NUMBER IS PLUS 1. 

5 COLUMN IS 2 GROUP INDICATE 
PICTURE IS A(9) SOURCE IS 
MONTHNAME OF RECORD- AREA (MONTH) 



(Execution Outout) 



|. 1 



JANUARY 



15 



A00. .. 
A02... 



PURCHASES AND COST. 



|. -| 



JANUARY 



21 



A03, 
A03, 



I J 

Figure 6 9. Sample Showing GROUP INDICATE 

Clause and Resultant Execution 

Output 



| Code 
l 

1 

Figure 70. 



T T 

| Control | 

| Character j Record 

.J. x 

2 3 



Format of a Report Record When 
the CODE Clause is Specified 



The following example shows how to 
create and print a report with a code of A. 
A Report Writer program contains the 
following statements: 

ENVIRONMENT DIVISION. 



SPECIAL-NAMES. 



IS CHR-A 
IS CHR-B. 



DATA DIVISION. 

FILE SECTION. 

FD RPT-OUT-FILE 

RECORDS CONTAIN 122 CHARACTERS 
LABEL RECORDS ARE STANDARD 
REPORTS ARE REP-FILE-A REP-FILE-B. 



REPORT SECTION. 
RD REP-FILE-A 



CODE CHR-A. 



RD REP-FILE-B CODE CHR-B. 
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The RPT-OUT-FILE must be written on a tape 
or mass storage device. A second program 
could then be used to print only the report 
with the code of A, as follows: 

DATA DIVISION. 

FD Kir j. — IN - FIuE 

RECORD CONTAINS 122 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS RPT-RCD. 

01 RPT-RCD. 

05 CODE-CHR PICTURE X. 
05 PRINT- PART. 

10 CTL-CHR PICTURE X. 

10 RECORD-PART PICTURE X(120). 

FD PRINT- FILE 

RECORD CONTAINS 121 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS PRINT-REC. 

01 PRINT-REC. 

05 FILLER PICTURE X(121). 



RD EXPENSE-REPORT CONTROLS ARE FINAL, 
MONTH, DAYY 



01 TYPE CONTROL FOOTING DAYY 
LINE PLUS x NEXT GROUP 
NEXT PAGE. 



01 TYPE CONTROL FOOTING MONTH 
LINE PLUS 1 NEXT GROUP 
NEXT PAGE. 



(Execution Output) 
EXPENSE REPORT 



PROCEDURE DIVISION. 



LOOP. READ RPT-IN-FILE AT END 
GO TO CONTINUE. 
IF CODE-CHR = "A" 
WRITE PRINT-REC FROM 

PRINT-PART 
AFTER POSITIONING CTL-CHR 

LINES. 
GO TO LOOP. 
CONTINUE. 



January 31 29. 30 

(Output for CF DAYY) 

January total 131.40 

(Output for CF MONIH) 



Note: The NEXT GROJP NEXT PAGu clause for 
the control footing DAY is not activated. 



Fl oating First Detail Rule 



C ont r ol Footing s a nd Page For m at 



Depending on the number and size of 
Control Footings (as well as the page depth 
of the report), all of the specified 
Control Footings may not be printed on the 
same page if a control break occurs for a 
high-level control. When a page condition 
is detected before all reguired Control 
Footings are printed, the Report Writer 
will print the Page Footing (if specified), 
skip to the next page, print the Page 
Heading (if specified), and then continue 
to print Control Footings. 

If the programmer wishes all of his 
Control Footings to be printed on the same 
page, he must format his page in the 
RD-level entry for the report (by setting 
the LAST DETAIL integer to a sufficiently 
low line number) to allow for the necessary 
space. 



The first presentation of a body group 
(PH, PF, CH, CF, or DE) that contains a 
relative line as its first line, will have 
its relative line spacing suppressed, and 
the first line will be printed on either 
the value of FIRST DETAIL or INTEGER PLUS 1 
of a NEXT GROUP clause from the preceding 
page. For example: 



A. If the following body group was the 
last to be printed on a page 



01 TYPE CF NEXT GROUP NEXT PAGE 

Then this next body group 

01 TYPE DE LINE PLUS 5 

would be printed on value of FIRST 
DETAIL (in PAGE clause). 

B. If the following body group was tne 
last to be printed on a page 

01 TYPE CF NEXT GROUP LINE 12 
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and after printing, line-counter = 40, 
then this next BODY GROUP 

01 TYPE DETAIL LINE PLUS 5 

would be printed on line 12+1 (i.e., 
line 13). 



Report Writer Routines 



At the end of the analysis of a report 
description entry (RD), the Report Writer 
routines are generated, based on the 
contents of the RD. Each routine has its 
own compiler- generated card number. 
Therefore, in the source listing, the last 
compiler-generated card number for an RD 
and that of the next source statement are 
not sequential. 



TABLE HANDLING CONSIDERATIONS 



Subscripts 



If a subscript is represented by a 
constant and if the subscripted item has a 
fixed length, the location of the 
subscripted data item within the table or 
list is resolved at compile time. 

If a subscript is represented by a 
data-name, the location is resolved at 
execution time. The most efficient format, 
in this case, is COMPUTATIONAL, with 
PICTURE size less than five integers". 

The value contained in a subscript is an 
integer that represents an occurrence 
number within a table. Every time a 
subscripted data-name is referenced in a 
program, the compiler generates up to 16 
instructions to calculate the correct 
displacement. Therefore, if a subscripted 
data-name is to be processed extensively, 
move the subscripted item to an 
unsubscripted work area, do all necessary 
processing, and then move the item back 
into the table. flYf" uhpn ^nh gcripts are 
rj^rrj p^y -" comput ational. subscrJ 
takes time ana cort 



actualdisplacement from the beginning of 
the table that corresponds to an occurrence 
number in the table. Address calculation 
for a direct index takes a maximum of four 
instructions; address calculation for a 
relative index takes a few more. 
Therefore, the use of index-names in 
referencing tables is more efficient than 
the use of subscripts. The use of direct 
indexes is faster than the use of relative 
indexes. 

Index-names can only be referenced in 
the PERFORM, the SEARCH, and the SET 
statements. 



Index Data Items 



Index data items are compiler-generated 
storage positions, one fullword in length, 
that are assigned storage within the COBOL 
program area. An index data item is 
defined by the USAGE IS INDEX clause. The 
programmer can use index data items to save 
values of index-names for later reference. 

Great care must be used when setting 
values of index data items. Since an index 
data item is not part of any table, the 
compiler places the value contained in the 
index-name or other index data item into 
the index data item (see the example given 
in "SET Statement"). Index data items can 
only be referenced in SEARCH and SET 
statements. 



OCCURS Clause 



A ts^l§_®l§.SSIlt is represented oy the 
subject of an OCCURS clause, and is 
equivalent to one level of a table. If 
indexing is to be used to reference a tabli: 
element, and the Format 2 (SEARCH kLL) 
statement is also to be used, the KEX 
option must be specified in the OCCURS 
clause. The table element must then be 
ordered upon the key(s) data-name (s) 
specified. 



DEPENDING ON Option 



Index-Names 



Index-names are compiler-generated 
items, one fullword in length, assigned 
storage in the TGT. An index-name is 
defined by the INDEXED BY clause. The 
value in an index-name represents an 



If a data item described by an OCCURS 
clause with the DEPENDING ON data- name 
option 1 is followed by nonsubordinate data 



*-For a discussion of the use of the OCCURS 
DEPENDING ON clause in a sort program, see 
"Sorting Variable-Length Records. " 



Programming Techniques 241 



items, a change in the value of data- name 
during the course of program execution will 
have the following effects: 

1. The size of any group described by or 
containing the related OCCURS clause 
will reflect the new value of 
data-name . 

2 a _ Hhene vex. a MOVE, .to.- a field- coniaiain-g- 

an OCCURS clause with the DEPENDING ON 
option is executed, the MOVE is made 
on the basis of the current contents 
of the object of the DEPENDING ON 
option. 

3. The location of any nonsubordinate 
items following the item described 
with the OCCURS clause will be 
affected by the new value of 
dat a-name . If the user wishes to 
preserve the contents of these items, 
the following procedure can be used: 
prior to the change in data-name, move 
all nonsubordinate items following the 
variable item to a work area; after 
the change in data-name , move all the 
items back. 

Note: The value of data- name may change 
because a move is made to it or to the 
group in which it is contained; or the 
value of data-name may change because the 
group in which it is contained is a record 
area that has been changed by execution of 
a READ statement. 

For example, assume that the Data 
Division of a program contains the 
following coding: 

01 ANYRECORD. 

05 A PICTURE S999 COMPUTATIONAL- 3. 
05 TABLEA PICTURE S999 OCCURS 100 

TIMES DEPENDING ON A. 
05 GROUPB. 

(Subordinate data items. ) 

(End of record. ) 



GROUPB items are not subordinate to TABLEA, 
which is described by the OCCURS clause. 
Assuming that WORKB is a work area with the 



same data structure as GROUPB, the 
following procedural coding could be used: 

1. MOVE GROUPB TO WORKB 

2. Calculate new value of A 

3. MOVE WORKB TO GROUPB 



T" 1 ^^, r* Wo? 



ot o r c~- , tnnc7x\icar" 



x/y 



putting the OCCURS clause with the 
DEPENDING ON option at the end of the 
record. 

Not e: Data-n a me can also change because of 
a change in the value of an item that 
redefines it. In this case, the group size 
and the location of nonsubordinate items as 
described in the two preceding paragraphs 
cannot be determined. 



SET Statement 



The SET statement is used to assign 
values to index-names and to index data 
items. 

When the SET statement assigns to an 
index-name the value of a literal, 
identifier, or an index-name from another 
table element, it is set to an actual 
displacement from the beginning of the 
table element that corresponds to the 
occurrence number indicated by the second 
operand in the SET statement. The compiler 
performs all tne necessary calculations. 
If the SET statement is used to assign an 
index-name to another index-name for the 
same table element, the compiler need make 
no conversion of the actual displacement 
value contained in the second operand. 

However, when an index data item is set 
to another index data item or to an 
index-name, or when an index-name is set to 
an index data item, the compiler is unable 
to change any displacement value it finds, 
since an index data item is not part of any 
table. Thus, no conversion of values can 
take place. If the programmer forgets 
this, programming errors can occur. 
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C (1, 1) 



C (2, 1) 



C (2, 2) 



D (1, 1, 1) 

D (1, 1, 2) 

D (1, 1, 3) 

D (1, 2, 1) 

r\ I 1 1 "> \ 

\-> \ J. , ^ | z. / 

D (1, 2, 3) 

D (2, 1, 1) 

D (2, 1, 2) 

D (2, 1, 3) 

D (2, 2, 1) 

D (2, 2, 2) 

D (2, 2, 3) 



Byte | 
NO. 

0| 

25 

50 

B (1) J J- 1 4, 75 

| (D (1, 2, 1) J E |F | 

100 

125! 

150 

175J 

200 
I {D (2, 1, 3) j E JF "| 

B (2) I j- + J, 225 

\ CD (2, 2, 1) | E |F | 

250 

275 

300 

L J 

Figure 71. Storage Layout for Table Reference Example 
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For example, suppose that a table has 
been defined as: 

01 A. 

02 B OCCURS 2 INDEXED BY II, 15. 

03 C OCCURS 2 INDEXED BY 12, 16. 

04 D OCCURS 3 INDEXED BY 13, 14. 
05 E PIC X(20). 
05 F PIC 9(5). 

Figure 71 shows how the table is laid 
out in main storage. 

Now, suppose it is necessary to 
reference D (2,2,3). The following steps 
are in co rrect : 

SET 13 TO 2. 

SET INDX-DATA-ITM TO 13. 

SET 12, II TO INDX-DATA-ITM. 

SET 13 UP BY 1. 

MOVE D(I1, 12, 13) TO WORKAREA. 

The value contained in 13 after the first 
SET statement is 25, which represents the 
beginning point (in bytes) of the second 
occurrence of D. When the second SET 
statement is executed, the value 25 is 
placed in INDX-DATA-ITM, and the third SET 
statement moves the value 25 into 12 and 
II. The fourth SET statement increases the 
value in 13 to 50. The calculation for the 



address D (II, 12, 13) would then be as 
follows : 



(address of D(1,1,D) + 25 + 25 + 50 = 
(address of D(l,l, 1) ) + 100 

where D(l, 1,1) represents the first 
occurrence of D. This is not the address 
of D (2, 2, 3). 

The following steps will find the 
correct address: 

SET 13 TO 2. 

SET 12, II TO 13. 

SET 13 UP BY 1. 

In this case, the first SET statement 
places the value 25 in 13. Since the 
compiler is able to calculate the lengths 
of B and C, the second SET statement places 
the value 75 in 12, and the value 150 in 
II. The third SET statement places the 
value 50 in 13. The correct address 
calculation will be: 

(address of D(l,l,l>> + 150 + 75 + 50 = 
(address of D(1,1,D) + 275. 

The rules for the SET statement are 
shown in Table 28. 
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Table 28. Rules for the SET Statement 



Sending | 



Receiving 

TndPY-name 




Identifier 



Index-name 



Index Data Item 



Identifier 
or Literal 



Set to value 
corresponding 
to occurrence 

Trmrajer 1 



Move without 
conversion 



Set to value 
corresponding 
to occurrence 



iraniLrerr 



Set to occurrence | 
number represented j 
by index-name j 
x. 



*-If index-name refer to the same table element move without conversion 







+— 




~ + 




Index Data 


Move without 


1 


Move without 


1 


— 


Item 


conversion 


1 
+ 


conversion 


1 
— + 





SEARCH Statement 



Only one level of a table (a table 
element) can be referenced with one SEARCH 
statement. Note that SEARCH statements 
cannot be nested, since an 
imperative-statement must follow the WHEN 
condition, and the SEARCH statement is 
itself conditional. 



There are two formats for the SEARCH 
statement. Format 1, SEARCH, is used for a 
serial search. Format 2, SEARCH ALL, is 
used for a binary search. 



Format 1 SEARCH statements perform a 
serial search of a table element. If the 
programmer knows that the "found" condition 
will come after some intermediate point in 
the table element, to speed up execution, 
he can use the SET statement to set the 
index-names at that point and search only 
part of the table element. If the table 
element is large, and must be searched from 
the first occurrence to the last, the use 
of Format 2 (SEARCH ALL) is more efficient 
than Format 1, since it uses a binary 
search technique; however, the table must 
then be ordered. 



In Format 1, the VARYING option allows 
the programmer to: 



Vary an index-name other than the first 
index-name stated for this table 
element. Thus, with two SEARCH 
statements each using a different 
index-name, reference can be made to 
more than one value in the same table 
element for comparisons, etc. 



• Vary an index-name from another table 
element. In this case, the first 
index-name specified for this table 
element is used for the search, and the 
index-name specified in the VARYING 
option is incremented at the same time. 
Thus, it is possible to step through 
two table elements at once. 



In Format 1, the WHEN con 
any relation condition, and 
multiple. If multiple WHEN 
stated, the implied logical 
OR — that is, if any one of 
conditions is satisfied, the 
imperative-statement followi 
condition is executed. If a 
of the SEARCH statement are 
before exiting from the sear 
WHEN condition with an AND 1 
connective must be written. 



dition can be 
can be 

conditions are 
connective is 
the WHEN 

ng the WHEN 
11 conditions 
to be satisfied 
ch, a compound 
ogical 



In Format 2, the SEARCH ALL statement, 
the table must be ordered on the KEY(S) 
specified in the OCCURS clause. Any KEY 
may be specified in the WHEN condition, but 
all preceding data-names in the KE5f option 
must also be tested. The test must be an 
"equal to" (=) condition, and the KE¥ 
data-name must be either the subject or 
object of the condition, or the name of a 
conditional variable with which the tested 
condition-name is associated. The WHEN 
condition can also be a compound condition, 
formed from one of the simple conditions 
listed above, with AND as the only logical 
connective. The KEY and its object of 
comparison must be compatible, as given in 
the rules of the relation test. 

To write a series of statements that 
will search the three-dimensional table 
discussed in the section "The SET 
Statement" , the programmer could write: 
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77 COMPARANDl PIC X(5). 
77 C0MPARAND2 PIC 9(5). 
01 A. 

05 B OCCURS 2 INDEXED BY II 15. 

10 C OCCURS 2 INDEXED BY 12 16. 

15 D OCCURS 3 INDEXED BY 13, 14. 
20 E PIC X(5). 
20 F PIC 9(5). 



(initialize comparandl and comparand2) 



For example, a user-defined table may be 
the following: 

01 TABLE. 

05 ENTRY-IN-TABLEE OCCURS 90 TIMES 
ASCENDING KEY-1, KEY-2 
DESCENDING KEY-3 
INDEXED BY INDEX- 1. 

10 PART-1 PICTURE 9(2). 

PICTURE 9(5). 

PICTURE 9(6). 

PICTURE 9*4). 

PICTURE 9(33). 

PTPTHRF; QlS). 



10 


KEY-1 


10 


PART- 2 


10 


KEY-2 


10 


PART- 3 


10 


KEY-3 



PERFORM SEARCH-TEST1 THRU SEARCH-EXIT1 
VARYING II FROM 1 BY 1 UNTIL II GREATER 
THAN 2 AFTER 12 FROM 1 BY 1 UNTIL 12 
GREATER THAN 2. 
ENTRY-NOENTRY1. GO TO ERROR- RECOVERYl. 



A search of the entire table can be 
initiated with the following instruction: 



SEARCH-TEST1. SET 13 TO 1. 

SEARCH D WHEN E (II, 12, 13) = 

COMPARAND1 AND 

F (II, 12, 13) = COMPARAND2 

SET 15 TO II 

SET 16 TO 12 

SET 12 TO 3 

SET II TO 3 

ALTER ENTRY- NOENTRY1 TO PROCEED TO 

ENTRY-PROCESSINGl. 
SEARCH- EXIT1. EXIT. 



ERROR-RECOVERYl . 



ENTRY-PROCESSING1 . 

MOVE E(I5, 16, 13) TO OUT-AREA1. 
MOVE F(I5, 16, 13) TO OUT-AREA2, 



SEARCH ALL ENTRY-IN-TABLEE AT 

END GO TO NOENTRY 
WHEN KEY-1 (INDEX-1) = VALUE-1 A.ND 

KEY-2 (INDEX-1) = VALUE- 2 

AND KEY-3 (INDEX-1) = VALUE-3 
MOVE PART-1 (INDEX-1) TO 

OUTPUT-AREA. 



The foregoing instructions will execute 
a search on the given array TABLE which 
contains 90 elements of 55 bytes and 3 
keys. The primary and secondary keys 
(KEY-1 and KEY-2) are in ascending order 
whereas the least significant key (KEY-3) 
is in descending order. If an entry is 
found in which three keys are equal to the 
given values (i.e., VALUE-1, VALUE-2 
VALUE-3) PART-1 of that entry will be moved 
to OUTPUT-AREA. If matching keys are not 
found in any of the entries in TABLE, the 
NOENTRY routine is entered. 



The PERFORM statement varies the indexed 
(II and 12) associated with table elements 
B and C; the SEARCH statement varies 13, 
which is associated with table element D. 



The values of II and 12 that satisf " the 
WHEN conditions of the SEARCH statement are 
saved in 15 and 16. II and 12 are then 
both set to 3 using the SET statement, so 
that upon return from the SEARCH statement 
control will fall through the PERFORM 
statement to the GO TO statement. 



If a match is found between a table 
entry and the given values, the index 
(INDEX-1) is set to a value corresponding 
to the relative position within the taole 
of the matching entry. If no match is 
found, the index remains at the setting it 
had when execution of the SEARCH ALL 
statement began. 



Compilation is faster if KEY(S) are 
tested in the SEARCH statement in the same 
order they appear in the KEY option. 



Subsequent references to the desired 
occurrence of table elements E and F make 
use of the index-names 15 and 16 in which 
the correct value was saved. 



Note that if KEY entries within the 
table do not contain valid values, then the 
results of the binary search will be 
unpredictable. 
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Building Tables 



When reading in data to build an 
internal table: 

1. Check to make sure the data does not 
exceed the space allocated for the 
table. 

2. If the data must be in sequence, check 
the sequence. 

3. If the data contains the subscript 
determining its position in the table, 
check the subscript for a valid range. 



When testing for the end of a table, use 
a named value giving the item count, rather 
than using a literal. Then, if the table 
must be expanded, only one value need be 
changed, instead of all references to a 
literal. 



Q UEUE STRUCTURE CONSIDER ATIONS 



In a COBOL teleprocessing (TP) program, 
a CD FOR INPUT allows the specification of 
one through three levels of sub-queues from 
which data can be received; this allows the 
COBOL object program, at execution time, to 
make use of pre-defined queue structures, 



and to access all or parts of such 
structures. For TP programs, such queue 
structures are analogous in function and 
form to the File Description IFD) entry and 
its associated 01 record description for 
file processing programs. If pre-defined 
queue structures are used, each lowest 
level sub-queue name in the structure 
corresponds to a DD name; the associated DD 
card must specify a TPROCESS entry in the 
message control program (MCP) terminal 
table). Figure 72 shows the configuration 
of one queue structure such that queue A is 
made up of sub-queues B and C, sub-queue B 
is made up of sub-queues D and E, and 
sub-queue D is made up of sub-queues H and 
I (where sub-queue H contains messages Zl 
and X2 and sub-queue I contains messages 
X3, X4, and X5), and so on. 



During program execution, when the user 
wishes to receive a message from a queue 
(or sub-queue) he need not place the names 
of all sub-queues in the input CD; he need 
specify only the SYMBOLIC QUEUE name, which 
may be the name of a pre-defined queue 
structure, or he may specify that name plus 
one or more sub-queue names — which allows 
him to access only that part of the entire 
structure that is needed. A COBOL 
ooject-time subroutine uses the name(s> 
placed in the input CD to determine which 
lowest-level sub-queue(s> and corresponding 
TCAM queue (s) can be used to fill the 
request. 



QUEUE 



SUB-QUEUE (1) 



SUB- QUEUE (2) 



SUB-QUEUE (3) 



MESSAGE 















Zl 


X3 


XI 


Z6 


Y7 


Yl 


X2 


XU 


Y3 


Z7 


Y8 


Y2 




X5 


Y5 
Z5 


Y6 







X6 



22 
Z3 
Z4 



Figure 72. A Queue Structure with Three Levels of Sub-Queues 
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//BLDRDS JOB user information 

//JOBLIB 1 DD DSN=SYSl.COBLIB,UNIT=2314, VOL=SER=DC160,DISP=OLD 

//SUBQS 2 EXEC PGM=ILBOQSU f REGION=96K 

//COBTPQD 3 DD DSN=SU3QPDS, UNIT=2314, VOL=SER=DC160, X 

// SPACE=(4000, (50 # 20 ( 1)) < DISP=(OLD 1 KEEP) 

//SYSPRINT* DD SYSOUT=A 

//SYSIN 5 DD * 

// 

QQEUE STRUCTURE DEFINITIONS FOR USE IN COBOL PROGRAMS WHICH PROCESS QUEUES AND 
SUB-QUEUES. 



QUEUE IS A. 

SUB-QUEUE-1 IS B. 

SUB-QUEUE- 2 IS D. 

SUB-QUEUE-3 IS H. 

SUB-QUEUE- 3 IS I. 
SUB-QUEUE-2 IS E. 

SUB-QUEUE-3 IS J. 

SUB-QUEUE-3 IS K. 
SUB-QUEUE-1 IS C. 

SUB-QUEUE-2 IS F. 

SUB-QUEUE-3 IS L. 

SUB-QUEUE-3 IS M. 
SUB-QUEUE-2 IS G. 

SUB-QUEUE-3 IS N. 

SUB-QUEUE-3 IS 0. 



Note : 



The parenthetical entries below are 



for illustrative purposes only, they may 
not appear in the program itself. 

(FD clause) 

(01 entry) 

(02 entry) 

(03 entry) 

(03 entry) 
(02 entry) 

(03 entry) 

(03 entry) 
(01 entry) 
(02 entry) 

(03 entry) 

(03 entry) 
(02 entry) 

(03 entry) 

03 entry) 



Notes : 



1. The data-set name SYS1.COBLIB represents the Version 4 COBOL Library. 

2. The utility program ILBOQSU (called the Queue Structure Description routine) 
creates a partitioned data set with one member for each complete queue structure 
defined. It has an alias name of BLDQS, which may be specified on the EXEC card 
instead. 

3. The partitioned data set must be described on a DD card with the reserved name 
//COBTPQD. The SPACE parameter on this card must request allocation in terms of 
4000-byte blocks. 

4. The SYSPRINT DD statement defines the output message and listing data set. 

5. The SYSIN DD statement defines the input to the program. The SYSIN data set must 
consist of 80-character records. 

Figure 73. A Sample Queue Structure Descripion 
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In order to do this, the user must have 
previously defined his queue structures in 
a form that is acceptable to the COBOL 
object-time subroutine. A utility program 
that functions as the Queue Structure 
Description routine (included in the 
Version 4 Library) makes this possible. 
Input to the Queue Structure Description 
routine consists of a series of statements 
that define queue structures. The 
statements are written in a COBOL-like 
format, similar to an FD entry and its 
associated record description entry. The 
Queue Structure Description routine 
produces as output a partitioned data set 
with one member for each complete queue 
structure. The sample listing shown in 
Figure 73 provides the queue definition 
statements that correspond to this queue 
structure. At the right of each statement, 
in parenthesis, is each FD entry 
equivalent. 

Each logical record in a queue structure 
description may include only a queue or 
sub-queue definition; it may not include, 
for example, the usual COBOL sequence 
number. (For a detailed description of the 
possible formats for input to the Queue 
Structure Description routine, see the 
Section "Rules for Queue Structure 
Description" in this chapter. ) 



ACCESSING QUEUE STRUCTURES THROUGH COBOL 



Once the user has defined and stored the 
queue structures, COBOL TP programs can 
utilize these structures. At execution 
time, the partitioned data set is described 
on a DD card with the name COBTPQD. If, 
for example, the user wanted to access 
messages described in the queue structure 
defined in Figure 73, a DD card specifying 
the partitioned data set SUBQPDS, as below, 
would be required. 

//COBTPQD DD DSN=SUBQPDS, DISP=OLD 

Additional DD cards would be required to 
link the message control program terminal 
table entries and the lowest-level 
sub-queue names. (For a description of 
terminal table entries, see the section 
"Terminal and Line Control Areas" in the 
chapter "Using the Teleprocessing 
Feature".) The name of the DD card may be 
defined either as the sub-queue name itself 
(for example, as H, I, J, K, L, M, N, or 0) 
or as a ddname that is equivalent to the 
lowest-level sub-queue name. This 
alternative approach permits the COBOL 
program to reuse SYMBOLIC SUB-QUEUE names 
without ambiguity. These two approaches 
are illustrated below. 



Methodl; The DD card associated with the 
queue definition SUB-QUEUE- 3 is H would be: 

//H DD QNAME=Q1 

Method_2: The DD card associated with the 
queue definition SUB-QUEUE- 3 is H(FIRSTMSG) 
would be: 

//FIRSTMSG DD QNAME=Q1 

where Ql is an entry in the terminal table 

Before a RECEIVE statement is executed, 
the user places (via a MOVE statement) the 
needed queue and sub-queue name(s) in the 
CD entry. When the RECEIVE statement is 
executed, the RECEIVE subroutine checks for 
the presence of the partitioned data set 
describing these queue structures. If the 
data set is present, the RECEIVE subroutine 
invokes a Queue Analyzer routine, which 
searches the partitioned data set for a 
member corresponding to the name in the 
SYMBOLIC QUEUE field, reads that member 
into main storage, and uses it to validate 
the SYMBOLIC SUB-QUEUE name(s) in the COBOL 
program input CD entry. The Queue Analyzer 
routine then determines the first valid 
name for the structure specified and gives 
this name to the RECEIVE routine. 

Names at the SUB-QUEUE-1 level take 
priority over names at the SUB-QUEUE- 2 
level. Names at the SUB-QUEUE-2 level take 
priority over names at the SUB-QUEUE- 3 
level. At any given level, names at the 
left take priority over, and are completely 
evaluated before, names at the right. 
(Taking advantage of this retrieval 
technique, the user can improve object-time 
performance by defining the most frequently 
used sub-queues at the left of the 
structure. Table 29 illustrates TCAM 
message retrieval. ) 

The RECEIVE subroutine then attempts to 
access the queue specified. If the DD card 
for this queue is not present, or if there 
are no messages in the associated MCP 
queue, the Queue Analyzer provides the 
RECEIVE routine with another valid name. 
The procedure is repeated until the RECEIVE 
routine accesses a message, or until there 
are no more queues to access. 

During a RECEIVE operation, a COBOL 
program using queue structures need not 
specify all levels of sub-queues. The 
highest level (QUEUE) must be specified; 
that level plus a SUB-QUEUE-1 may also be 
specified; or all four levels may be 
specified. If a lower level is specified, 
then all higher levels must also be 
specified. 

If the COBOL programmer wishes to access 
the next message in the queue structure, 
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Table 29. Sample Message Retrieval Options 

r 



Input CD 



Message Returned by the MCP 



CD CDNAME-IN FOR INPUT 

SYMBOLIC QUEUE IS data-name-1. 
(where data-name-1 contains * A* ) 

CD CDNAME-IN FOR INPUT 

SYMBOLIC QUEUE IS data-name-1. 

SYMBOLIC SUB-QUEUE-1 IS data-name- 2. 
(where data-name-1 contains 'A' and 
data-name-2 contains ' C* 1 

CD CDNAME-IN FOR INPUT 

SYMBOLIC-QUEUE IS data-name-1, 
SYMBOLIC-QUEUE- 1 IS data-name-2 , 
SYMBOLIC- QUEUE- 2 IS data-name-3. 
(where data-name-1 contains 'A', 
data-name-2 contains ' B*, 
and data-name-3 contains * E* 1 



Message Zl 



Message Y7 



Message XI 



Not e: Data-name-1, data-name-2, and so on, refer to the optional clauses of a queue 
structure defined under "Rules for Queue Structure Description" in this chapter. 



regardless of which sub-queue that message 
may be in, he specifies the queue name 
only, and initializes the sub-queue-names 
to SPACES. The Queue Analyzer, when 
supplying the message, returns to the COBOL 
.o±^e£Lt^.proxp:am..any..-appli<^J3le---sub==J5«ette 
names via the data items in the associated 
input CD. If, however, the programmer 
wishes the next message in a given 
sub-queue, he must specify both the queue 
name and any applicable sub-queue names, 
Once a program has begun receiving any part 
of a message from a queue (or sub- queue ) , 
subsequent requests must specify both the 
queue-name and any applicable 
sub-queue-names until end of message is 
indicated. Table 29 illustrates the 
relationship between the information 
contained in the input CD at object time 
and the message (s) accessed when the 
RECEIVE statement is executed (where each 
example refers to the queue structure 
pictured in Figure 72). 



Spec ifying ddname s wi th E lementa ry 
Sub- Queues 



Suppose that an application program is 
written to accept TP messages as input to 
an inventory control process. Each of five 
different locations transmits data on four 
different parts. The diagram in Figure 74 
illustrates the relationship between the 
input messages and the four different parts 
for each location. 



Each elementary, or lowest-level, queue 
in the structure must specify the name of a 
DD card, which in turn names a TPROCESS 
entry. While the example, as shown in 
Figure 74, is not ambiguous (that is, 
IWENT-QRY^GHtGAGO, PARTA is distinct from 
INVENTORY. LOS-ANGELES. PARTA), the 
elementary queues by themselves are not 
(that is, the elementary name PARTA, which 
corresponds to a ddname, can be any one of 
five different PARTA' s). To eliminate this 
ambiguity, whenever there are duplicate 
names in the lowest level of a queue 
structure, the user must define ddnames in 
addition to the sub-queue names at the 
lowest level when he defines the structure 
to the Queue Structure Description routine. 
Then the object-time Queue Analyzer routine 
automatically associates the fully 
qualified queue structure names with the DD 
names required. Accordingly, in this 
example : 

NEW- YORK. PARTA could have ddname DDL 

NEW- YORK. PARTB could have ddname DD2. 

NEW- YORK. PARTC could have ddname DD3. 

NEW- YORK. PARTD could have ddname DD4. 

CHICAGO. PARTA could have ddname DD5. 

CHICAGO. PARTB could have ddname DD6. 

and so forth. In this way, each elementary 
queue has a unique designation; yet the 
COBOL program can refer to the sub- queue 
names without ambiguity. 
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SUB-QUEUE-2 
PARTA(DDl) 
PARTB(DD2) 
PARTC(DD3) 
PARTD(DD4) 



SUB-QUEUE-1 



NEW-YORK 



QUEUE 



PARTA(DD5) 
PARTB(DD6) 
PARTCCDD7) 
PARTD(DD8) 



CHICAGO 
^ 



PARTA(DD9) 
PARTB(DDIO) 
PARTC(DDll) 
PARTD(DD12)- 



ST-LOUIS 



INVENTORY 



PARTA(DD13) 
PARTB(DD14) 
PARTCCDD15) 
PARTDCDD16) 



DENVER 
| 1 



LOS-ANGELES 
J 



PARTACDD17) 

PARTB(DD18) 

PARTC(DD19) 

PARTD ( DD2 ) J 

Figure 74. Using ddnames with Queue Structures 
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Format 



{{ 



( QUEUE 

( SUB- QUEUE -1 
| SUBQ1 



IS data 



IS data-name-2 [ (ddname-) ] } . 



f SUB-QUEUE- 2 | 
[[ ) > IS data-name- 3 [ (ddname) ]]. . 

) sUB n 2 

( SUB-QUEUE- 3 
[ ) > IS data-name-4[( ddname- 3)]] 

JSUBQ3 



.]}, 



Rules for Queue Structure Descrip tion 



For each member of the partitioned data 
set, the input to the Queue Structure 
Description Routine must take the format 
above. 

The clauses of the queue structure may 
be written free form; however, only one 
clause may appear on each 80-character 
record. At - least one sttb^Tqueue level must 
be specified; no more than 200 sub-queue 
names may be specified in one queue 
structure. 

The sub-queues at each level must be 
specified to the Queue Structure 
Description routine in left-to-right order* 
When the queue structure is referred to at 
object program execution time, names at a 
higher level take priority over names at a 
lower level. At a given level in the queue 
structure, names to the left take priority 
over names to the right. 

A queue structure need not include all 
levels of sub-queues. However, if a lower 
level is included in one leg of a queue 



structure, then that leg must include all 
higher levels. 



Each clause of the structure may 
optionally be followed by a period. 



Data-name-1 is the name of the queue 
structure, and becomes the name of that 
member of the partitioned data set. 



D ata-name-2 though data- name- U are 
sub-queue names within the data set member. 

Note : A data-name cannot contain more than 
12 characters. 

Each data-name at the lowest 
(elementary) level of a leg of the queue 
structure may be a ddname ; alternatively, 
each such data-name may be followed by a 
parenthesized ddname. If a parenthesized 
ddname follows a sub-queue name, the left 
parenthesis must immediately follow the 
sub-queue name with no intervening spaces. 
There must be no spaces between the 
parentheses and the ddname. 
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CALLING AND CALLED PROGRAMS 



A COBOL program can refer to and pass 
control to other COBOL programs, or to 
programs written in other languages. A 
program in another language can refer to 
and pass control to a COBOL program. A 
program that refers to another program is 
calling program. A program that is 
referred to is a c alled program. Control 
is returned from a called program to the 
first instruction following the calling 
sequence in the calling program. 



A called program can also be a calling 
program; that is, a called program can, in 
turn, call another program. However, a 
called program cannot call the program that 
called it, an earlier calling program, or 
itself. In Figure 75, for instance, 
program A calls program B; program B calls 
program C. Therefore: 

1. A is considered a calling program by E. 

2. B is considered a called program by A. 

3. B is considered a calling program by C. 

4. C is considered a called program by B. 



Usually called and calling programs to 
be executed as a single job step are 
link-edited together; they must all oe 
included in the same load module. However, 
with the COBOL dynamic call feature a 
programmer can request that a called 
program be link-edited into a separate 
module and called only if it is needed (see 
the section "Dynamic Subprogram Linkage", 
in this chapter). 

This chapter describes the accepted 
linkage conventions for calling and called 
programs in both COBOL and assembler 
language and discusses how such programs 
are link-edited. An example is provided to 
illustrate the coding required to have 
proper interface between both COBOL and 
assembler language calling and called 
programs. In addition, it includes a 
discussion of overlay design in which 
different called programs may, at different 
times, occupy the same area in main 
storage. Another example is provided to 
illustrate one method of accomplishing 
program linkage using the dynamic overlay 
technique. 



SPECIFYING LINKAGE 



Control is returned in the same order of 
calling; that is, a called program (program 
C) returns control to its own calling 
program (program B), not to an earlier 
calling program (program A). Compiler- 
generated switches (e.g., ON and ALTER) are 
not reinitialized upon each entrance to the 
called program, that is, the program is in 
the last executed state unless it has been 
the object of a CANCEL statement. 



Whenever a program calls another 
program, a link must be established between 
the two. The calling program must state 
the entry point of the called program and 
must specify any identifiers to be passed. 
The called program must have an entry point 
and must be able to accept the identifiers. 
In addition, the called program must 
establish the linkage for the return of 
control to the calling program. See Figure 
76 for an example of the linkage statements 
required in a typical calling/called 
situation. 



I 

Calling | 
program of B |- 
I 
I 

I 

j 



Called | 
program of A| 

I- 

Calling | 
program of cj 



Called 
program of B| 



L J 



Figure 75. Calling and Called Programs 
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LINKAGE IN A CALLING COBOL PROGRAM 



A calling COBOL program must contain the 
following statement at the point at which 
another program is to be called: 



literal-1 



CALL 



identif ier-1 
[USING identifier-list]. 



The literal-1 or PROGRAM-ID is the name of 
the entry point in the called program. It 
is the same name that appears in the CALL 
statement of the program that calls this 
program that the compiler uses. The 
identifier-list is one or more data-names 
that correspond to the identifier-list of 
the' CALL statement of the calling program. 
Each data name of the identifier-list must 
be defined in the Linkage Section of the 
Data Division and must have a level number 
of 01 or 77. 



T ■! 4-^-^^> 1 ^1 r\-*~ 4-V.irv ^r\r\*- es-r**- c? r\f 



^o>->4- A f-i or-1 



r^f 4-V.o 



O LULCUlCllU^ 



I \~ UX^ 



must be either the name of the program that 
is being called or the name of an entry 
point in the called program. The first 
eight characters of literal-1 or 
identifier-1 are used to make the 
correspondence between the calling program 
and the called program. The 
identifier-list is one or more data-names, 
called identifiers and separated by blanks, 
that are to be passed to the called 
program. 

If the called program is an 
assembler-language program, the identifier 
in the USING phrase may also be a file-name 
or a procedure-name. If the identifier in 
the USING phrase is a file-name, the COBOL 
compiler passes the address of the DCB for 
a -queued" file ; or the -address of the ~~&ECB 
for a basic file, as this entry of the 
identifier-list. This can be used to test 
bits in the DCB or DECB or to enter some 
options in the DCB. However, when changing 
a field of the DCB, precautions should be 
taken not to contradict the information in 
other fields or the information in the 
object code supplied by the compiler, job 
control language, or other sources. When 
the identifier in the USING phrase is a 
procedure-name, the value passed is the 
beginning address of the procedure. If no 
identifiers are passed, the USING clause is 
omitted. 



LINKAGE IN A CALLED COBOL PROGRAM 



A called COBOL program must contain two 
statements. 



inserted at the point at which control is 
to be returned to the calling program: 

GOBACK. 

or 

EXIT PROGRAM. 



The GOBACK or EXIT PROGRAM statement 
enables restoration of necessary registers 
and returns control to the point in the 
calling program immediately following the 
calling sequence. 

Note: The GOBACK and EXIT PROGRAM 
statements may be used in a main program, 
with - the result that any tCOBOL -program can — 
be used as either a calling or a called 
program, if written with this end in mind. 
If a GOBACK statement appears within the 
main program, control is returned 
immediately to the system; if an EXIT 
PROGRAM statement appears, it is simply 
regarded as a null instruction. 

A called program may pass a completion 
code to its caller by storing a value in 
RETURN-CODE. The calling program may 
interrogate RETURN-CODE after a return is 
made from a called program to determine the 
completion code. 

Note: RETURN-CODE may also be used to pass 
a completion code to the system at the end 
of a run unit. 



One of the following statements must be 
inserted to name the point where the 
program is to be entered: 

ENTRY literal-1 

[USING identifier-list]. 

or 

PROCEDURE DIVISION [USING 
identifier-list] . 



With the dynamic subprogram linkage 
feature, a called program need not be 
link-edited with the main program. It may 
instead be link-edited into a separate load 
module, so that at execution time it is 
loaded if and only if it is called. 
Accordingly, the first dynamic call to a 
subprogram obtains a fresh copy of the 
subprogram. Subsequent calls to the same 
subprogram, by either the original caller 
or any other subprogram in the same 
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region/partition, result in a branch to the 
same copy of the subprogram in its 
last-used state until the subprogram is 
cancelled the first call following a CANCEL 
statement results in a branch to a fresh 
copy of the subprogram. 

Specification of the DYNAM option in the 
PARM field of the EXEC statement (see the 
section on "Compiler Options" in the 
chapter entitled "Job Control Procedures") 
makes all calls dynamic. If NODYNAM is in 
effect, through either user specification 
at compile time or as the default option, 
only CALL identifier statements are 
dynamic; when NODYNAM is in effect, CALL 
literal statements are static. (For a 
discussion of the formats possible with the 
CALL statement, see the publication IBM_OS 
Full Ame ric an Nat ional Stan da rd COBOL. ) 

For an example of a COBOL program that 
takes advantage of the dynamic CALL/CANCEL 
feature, see Figure 76 in this chapter. 



Not es : 

1. When the dynamic CALL is used, the 
main program and all subprograms in 
one region/partition should take 
advantage of the COBOL Library 
Management Facility (see the 
"Libraries" chapter). Even when the 
DYNAM option is not specified, a 
program with CALL identifier or CANCEL 
identifier statements requires the 
Library Management Feature. 



2. The USING option should be included in 
the CALL statement only if there is a 
USING option in the called entry 
point. 



3. A segmented program may be called out 
only by its PROGRAM-ID or by an entry 
point within the root segment. 



//CALLJOB 

//STEP1 

//COB.SYSIN 



/* 

//LKED.SYSLMOD 

// 

/* 



JOB user information 

EXEC UCOBFCL, PARM. COB=* DYNAM, RESIDENT' 

DD * 

IDENTIFICATION DIVISION 

PROGRAM-ID. SUBPR0G1. 

AUTHOR. J. SMITH 

REMARKS. 

THIS SUBPROGRAM IS CALLED BY THE MAIN PROGRAM. 

IT ISSUES A MESSAGE TO INDICATE WHETHER IT IS 

IN INITIAL OR LAST-USED STATE, AND THEN RETURNS 

TO THE MAIN PROGRAM. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION^ 
SOURCE-COMPUTER. IBM-360. 
OBJECT-COMPUTER. IBM-360. 
DATA DIVISION. 
WORKING- STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
PROCEDURE DIVISION. 

IF SWITCH=0 DISPLAY 'SUBPROG1 CALLED — IN 
INITIAL STATE' 

GO TO RETURN-POINT. 

DISPLAY ' SUPROGl CALLED — IN LAST-USED STATE'. 
RETURN-POINT. 

ADD 1 TO SWITCH. 

EXIT PROGRAM. 

DD DSN=SUBPROGS, UNIT=2314, VOL=SER=XXXXXX, 
DISP= (NEW, KEEP) , SPACE=(TRK, (5,1,1)) 



Note: When a subprogram is called dynamically, the (NAME and/or ALIAS) option of the 
linkage editor is used to identify the module that is accessed by an OS LOAD macro at 
execution time (see the section entitled "Link-editing COBOL Programs"). 

L 

Figure 76. Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 1 of 3) 
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//CALLJ0B2 

//STEP1 

//COB.SYSIN 



//LKED. SYSLMOD 
/* 



JOB user information 

EXEC UCOBFCL, PARM. COB=' DYNAM, RESIDENT' 

DD * 

IDENTIFICATION DIVISION. 

PROGRAM-ID. SUBPROG2. 

AUTHOR. J. SMITH 

REMARKS. 

THIS SUBPROGRAM IS CALLED BY THE MAIN PROGRAM. 

IF IT IS IN INITIAL STATE, IT ISSUES A MESSAGE 

TO THAT EFFECT AND RETURNS TO THE MAIN PROGRAM. 

IF NOT, IT ISSUES A MESSAGE THAT IT IS IN THE 

LAST-USED STATE, CANCELS SUBPROG1 VIA A CANCEL 

IDENTIFIER* AND RETURNS TO THE MAIN PROGRAM. 
ENVIRONMENT DIVISION. 
CONFIGURATION DIVISION. 
SOURCE-COMPUTER. IBM-360. 
OBJECT- COMPUTER. IBM-360. 
DATA DIVISION. 
WORKING- STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
77 CANCL-ID PIC X(8). 
PROCEDURE DIVISION. 

IF SWITCH=0 DISPLAY 'SUBPROG2 CALLED — IN INITIAL STATE' 
GO TO RETURN-POINT. 

DISPLAY ' SUBPROG2 CALLED — IN LAST-USED STATE'. 

DISPLAY 'SUBPROG2 CANCELLING SUBPROG1' . 

MOVE 'SUBPROGl' TO CANCL-ID. 

CANCEL CANCL-ID. 
RETURN-POINT. 

ADD 1 TO SWITCH. 

EXIT-PROGRAM. 

DD DSN=SUBPROGS,UNIT=2314, VOL=SER=XXXXXX, DISP=OLD 



Figure 76. Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 2 of 3) 
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//CALLJ0B3 
//STEP1 
//COB. SYSIN 



/* 

//GO. STEPLIB 

//GO. SYSOUT 

/* 



JOB user information 

EXEC UCOBFCLG, PARM. COB=' DYNAM, RESIDENT 1 

DD * 

IDENTIFICATION DIVISION. 

PROGRAM- ID. MAINPROG. 

AUTHOR, J= SMITH 

REMARKS. 

THIS IS A MAIN PROGRAM. IT CALLS SUBPROGl AND 
SUBPROG2 TWICE. ON THE FIRST CALL, EACH SUBPROGRAM 
SHOULD BE A FRESH COPY (THAT IS, IN INITIAL STATE). 
ON THE SECOND CALL, EACH SUBPROGRAM SHOULD BE IN ITS 
LAST-USED STATE. WHEN SUBPROG2 IS CALLED THE SECOND 
TIME, IT CANCELS SUBPROGl. THEN MAINPROG CALLS 
SUBPROGl AGAIN, AND AGAIN A FRESH COPY OF THIS 
SUBPROGRAM SHOULD BE MADE AVAILABLE. 
THE OUTPUT FROM THIS RUN SHOULD READ AS FOLLOWS: 



•BEGIN MAINPROG. 
MAINPROG CALLING 
SUBPROGl CALLED - 
MAINPROG CALLING 
SUBPROG CALLED — 
MAINPROG CALLING 
SUBPROG CALLED — 
MAINPROG CALLING 
SUBPROG2 CALLED - 
SUBPROG 2 CANCELLI 
MAINPROG CALLING 
SUBPROGl CALLED - 
MAINPROG CANCELLI 
END MAINPROG. • 



SUBPROGl. 

- IN INITIAL STATE. 
SUBPROG2. 

IN INITIAL STATE. 
SUBPROGl. 

IN LAST-USED STATE. 
SUBPROG2. 

- IN LAST-USED STATE. 
NG SUBPROGl. 
SUBPROGl. 

- IN INITIAL STATE. 

NG SUBPROGl AND SUBPROG2. 



ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-360. 
OBJECT-COMPUTER. IBM-360. 
DATA DIVISION. 
WORKING-STORAGE SECTION. 
77 SWITCH PIC 9 VALUE 0. 
77 CALLID PIC X(8). 
PROCEDURE DIVISION. 

DISPLAY 'BEGIN MAINPROG'. 
START- CALLS. 

IF SWITCH IS LESS THAN 2 PERFORM CALLl. 

PERFORM CALL2. 

GO TO START- CALLS. 

PERFORM CALLl. 

DISPLAY 'MAINPROG CANCELLING SUBPROGl AND SUBPROG2' 

CANCEL * SUBPROGl ' , ' SUBPROG2 ' . 

DISPLAY • END MAINPROG' . 

STOP RUN. 
CALLl. 

MOVE 'SUBPROG' TO CALLID. 

DISPLAY ' MAINPROG CALLING SUBPROG' . 

CALL CALLID. 
CALL2. 

MOVE 'SUBPROG2' TO CALLID. 

DISPLAY 'MAINPROG CALLING SUBPROG2' . 

CALL CALLID. 

ADD 1 TO SWITCH. 

DD DSN=SUBPROGS,UNIT=2314, VOL=SER=XXXXXX,DISP=OLD 
DD SYSOUT=A 



Figure 76. Sample Calling and Called Programs Using Dynamic CALL and CANCEL Statements 
(Part 3 of 3) 
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Corr esponde nce of Identifiers in Calling 
a nd_ Call ed Progra ms 



The number of data-names in the 
identifier list of a calling program must 
be the same as the number of data-names in 
the identifier list of the called program. 
There is a one-to-one correspondence; that 
is, the first identifier of the calling 
program is passed to the first identifier 
of the called program, the second 
identifier of the calling program is passed 
to the second identifier of the called 
program, and so forth. 



FILE-NAME AND PROCEDURE-NAME ARGUMENTS 



A calling COBOL program that calls an 
assembler-language program can pass 
file-names and procedure-names, in addition 
to data-names, as identifiers. In the 
actual identifier-list that the compiler 
generates, the procedure- name is passed as 
the address of the procedure. For a queued 
file, the file-name is passed as the 
address of the DCB (Data Control Block) ; 
for a basic file, the file-name is passed 
as the address of the DECB (Data Event 
Control Block). 



Only the address of an identifier list 
is passed. Consequently, the data-name 
that is an identifier of the calling 
program and the data-name that is the 
corresponding identifier of the called 
program both refer to the same locations in 
main storage. The pair of names, however, 
need not be identical, but the data 
descriptions must be equivalent. For 
example, if an identifier of the calling 
program is a level-77 data-name of a 
character string of length 30, its 
corresponding identifier of the called 
program could also be a level-77 data-name 
of a character string of length 30, or the 
identifier . of. the called, program, could he a 
level- 01 name with subordinate names 
representing character strings whose 
combined length is 30. 



Although all identifiers of the called 
program in the ENTRY statement must be 
described with level numbers of 01 or 77, 
there is no such restriction made for 
identifiers of the calling program in the 
CALL statement. An identifier of the 
calling program may be a qualified name or 
a subscripted name. When a group item with 
a level number other than 01 is specified 
as an identifier of the calling program, 
proper word-boundary alignment is required 
if subordinate items are described as 
COMPUTATIONAL, COMPUTATIONAL- 1, or 
COMPUTATIONAL- 2. If the identifier of the 
calling program corresponds to a level-01 
identifier of the called program, 
doubleword alignment is required. 



LINKAGE IN A CALLING OR CALLED 
ASSEMBLER- LANGUAGE PROGRAM 



In a COBOL program, the expansions of 
the linkage statement provide the save and 
return coding that is necessary to 
establish linkage between the calling and 
the called programs. Assembler-language 
programs must be prepared in accordance 
with the basic linkage conventions of the 
operating system. Table 30 shows the 
conventions for use of general registers as 
linkage registers. _ 



Convent ions Used in a Calling 
Assembler-Language Program 



A calling assembler-language program 
must reserve a save area of 18 words, 
beginning on a fullword boundary, to be 
used by the called program for saving 
registers. It must load the address of 
this area into register 13. If the program 
is to pass identifiers, an identifier list 
must be prepared, and the address of the 
identifier list must be loaded into 
register 1. The calling program must load 
the address of the return point into 
register 14, and it must load the address 
of the entry point of the called program 
into register 15. 
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Table 30. Linkage Registers 



Register 
Number 



Register 
Use 



Contents 



1 
13 

15 



Identifier 
Save Area 

Return 
Entry Points- 



Address of the list that is passed to the called program. 

Address of an area (of, 18 fullwords) to be used by the called 
program to save registers. 

Address of the location in the calling program to which 
control should be returned after execution of the called 
program. 

Address of the entry point in the called program to which 
control is to be transferred. 



^-Register 15 is also used as a return code register. The return code indicates 
whether or not any exceptional conditions occurred during execution of the called 
program. 



The identifier list is a group of 
contiguous fullwords, each of which is an 
address of a data item to be passed to the 
called program. The identifier list must 
begin on a fullword boundary. The 
high-order bit of the last identifier, by 
convention, is set as a flag of one to 
indicate the end of the list. Figure 77 
shows a portion of an assembler-language 
program that illustrates the conventions 
used in a calling program. 



A GOBACK statement or a STOP RUN 
statement issued within a COBOL program 
will (always for STOP RUN, but only in a 
main program for GOBACK) reference the 
COBOL library subroutine ILBOSRV. 
Furthermore, the STOP RUN statement will 
end the run unit , which is assumed to begin 
with the highest-level COBOL program 
called. To circumvent this assumption, a 
higher-level assembler language program 
must call the COBOL library subroutine 
ILBOSTP0 before making any calls to other 
COBOL programs. This should be done as 
soon as possible after entry to the 
assembler-language program, as part of the 
program* s initialization procedure. 



Q2QY§Ilti2D:S_Used_in_a_Called_Assembler2 
Languag e Program 



A called assembler-language program must 
save the registers and store other 
pertinent information in the save area 
passed to it by the calling program (the 
layout of the save area is shown in Figure 
79). A called program must also contain a 
return routine that (1) loads the address 
of the save area back into register 13, 
(2) restores the contents of other 
registers, loading the return address in 
register 14, and (3) optionally, sets flags 
in the high-order eight bits of word 4 of 
the save area to l's to indicate that the 
return occurred. It can then branch to the 
address in register 14 to complete the 
return. 



Figure 85 shows a portion of an 
assembler- language program that illustrates 
the conventions used in called programs 
that are also calling programs. Figure 86 
shows the JCL suggested for compiling, 
link-editing, and executing a calling 
assembler-language program and a called 
COBOL program. 
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AREA 



LA 



DS 



13, AREA 



18F 



CALLING SEQUENCE 

LA 1,ARGLST 

CALL C0BREGN2 



* PARAMETER LIST 

DS OF 
ARGLST DC X'80' 

DC AL 3 (ARGUMENT) 
ARGUMENT DC C'l' 



LOADS THE ADDRESS OF THIS PROGRAM' S SAVE AREA INTO 
REGISTER 13. 



RESERVES 18 WORDS FOR THE SAVE AREA 



LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER 
LIST TO BE PASSED. TRANSFERS CONTROL TO THE ENTRY 
POINT OF THE CALLED PROGRAM. (THE CALL MACRO 
INSTRUCTION GENERATES CODING THAT LOADS A V-TYPE 
ADDRESS CONSTANT — COBREGN2 — INTO REGISTER 15 AND 
PLACES INTO REGISTER 14 THE RETURN ADDRESS, THAT IS, 
THE ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION. 



THIS PARAMETER LIST CONTAINS ONLY ONE ARGUMENT. 
FIRST BYTE OF LAST ARGUMENT (ONLY 
ARGUMENT IN THIS PROGRAM) SETS BIT 
TO 1. 



Not e: Since the calling program containing this coding could previously have been 
called by another program, it also could establish linkage between the save area it has 
received and the save area it passes to the called program. It would store in word 
three of the old save area the address of the new save area, and it would store in word 
two of the new save area the address of the old save area. 

Figure 77. Sample Linkage Coding Used in a Calling Assembler-Language Program 



COMMUNICATION WITH OTHER LANGUAGES 



An American National Standard COBOL 
program may communicate at object time with 
programs written in other source program 
languages, such as COBOL F, PL/1, FORTRAN, 
and, as in the foregoing discussion, 
assembler language. The relatively few 
problems that may arise in using American 
National Standard COBOL with COBOL F 
usually have to do with slightly different 
boundary alignments, slack-byte insertion, 
different meanings for the same reserved 
word, and so on. 

There is a greater disparity between 
American National Standard COBOL and 
FORTRAN, much of it stemming from the basic 
differences in the applications for which 
these languages were developed. (FORTRAN 
is process oriented and does comparatively 
little file processing; COBOL, on the other 
hand, is definitely file oriented and is 
not mathematically self-sufficient. ) Care 
must be taken, therefore, in attempting to 
pass arguments between American National 
Standard COBOL and FORTRAN programs. 

The use of COBOL and PL/I together 
presents such a large number of problems 



that a considerable amount of study is 
necessary to implement anything but the 
most basic application. For further 
information, see the publications IBM OS 
Lin ka ge Editor and Loader , Order 
NO. GC28-6538, and IBM OS P L/I (F) 
Pro gr ammer ' s Guide , Order No. C28-6594. 



Abnormal terminations in non-COBOL 
programs calling COBOL programs compiled 
with either the STATE or the SYMDMP option 
(see the chapter entitled "Symbolic 
Debugging Features") cause generation of 
the following misinformation: 



Incorrect number for the statement 
responsible for the abnormal 
termination. The last COBOL statement 
in the called program executed before 
the return to the calling non-COBOL 
program is given in the "Last Card 
Number Executed" message. 

Incorrect PROGRAM-ID when such an 
abnormal termination occurs after 
return from the called COBOL program. 
The PROGRAM-ID message contains the 
user-specified name for the called 
COBOL program. 
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SAMPLE CALLING AND CALLED PROGRAMS 



The following set of programs (Figure 
76) contains a sample COBOL main-line 
program, COBMAIN, which calls COBOL and 
assembler-language programs using arguments 
that represent a data-item and a file-name. 

Some of the called programs (COBOL1, 
COBOLlB, and ASSMPGM) are themselves 



calling programs. Program COBREGNO is 
called by several programs, each of which 
enters at a different entry point within 
the program. 



The assembler language program, ASSMPGM 
shown in Figure 78 (Part 6A) , is 
illustrated in part in Figures 77 and 85, 
where sample linkage coding methods are 
demonstrated. 



IDENTIFICATION DIVISION. 
PROGRAM-ID. COBMAIN. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-360-F50. 
OBJECT-COMPUTER. IBM-360-F50. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-X ASSIGN TO UR-2540R-S-INFILE. 
I-0-CONTROL. 
DATA DIVISION. 
FILE SECTION. 
FD FILE-X 

RECORD CONTAINS 80 CHARACTERS 

LABEL RECORD IS OMITTED. 
01 IN-REC. 

05 TYPEN PIC X. 

05 HOLDER PIC X. 

05 FILLER PIC X(78). 
WORKING-STORAGE SECTION. 
77 SIGNAL PIC X(8). 
PROCEDURE DIVISION. 



OPEN INPUT FILE-X. 

READ FILE-X AT END GO TO CLOSE-FILE. 



CALL 'COBOL1* USING IN-REC. 



CALL •COBREGNl' USING IN-REC. 



CALL 'ASSMRTN' USING SIGNAL. 



CLOSE-FILE. CLOSE FILE-X. 



STOP RUN. 



Figure 78. Sample Calling and Called Programs (Part 1 of 6) 
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IDENTIFICATION DIVISION. 

PROGRAM- ID. COBOL1. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-360-F50. 

OBJECT-COMPUTER. IBM-36 0-F50. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O-CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING- STORAGE SECTION. 

77 TRANS-COBL PIC X(7). 

LINKAGE SECTION. 

01 PASS-REC. 

05 FILLER PIC X. 

05 TRANS- VALUE PIC X. 

05 FILLER PIC X(78). 
PROCEDURE DIVISION USING PASS-REC. 



CALL 'COBOL1A' USING TRANS-COBl. 



CALL 'COBOLIB' USING TRANS-COBl. 



j GGBACK. - . _ __j_ 



L. 



Figure 78. Sample Calling and Called Programs (Part 2 of 6) 



.j 



IDENTIFICATION DIVISION. 

PROGRAM- ID. COBOL1A. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-36 0-F50. 

OBJECT-COMPUTER. IBM-36 0-F50. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O-CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

LINKAGE SECTION. 

77 TRANS-COB1A PIC X(7). 

PROCEDURE DIVISION USING TRANS-COBlA, 



GOBACK. 



Figure 78. Sample Calling and Called Programs (Part 3 of 6) 
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IDENTIFICATION DIVISION. 

PROGRAM-ID. COBOL1B. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-36 0-F50. 

OBJECT-COMPUTER. IBM-360-F50. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O-CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

77 TRANS-COBREGN PIC X(7). 

LINKAGE SECTION. 

77 TRANS-COB1B PIC X(7). 

PROCEDURE DIVISION USING TRANS-COB1B. 



CALL 'COBREGNO' USING TRANS-COBREGN. 



GOBACK. 
Figure 78. Sample Calling and Called Programs (Part 4 of 6) 



r 

IDENTIFICATION DIVISION. 

PROGRAM-ID. COBREGNO. 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-36 0-F50. 

OBJECT-COMPUTER. IBM-360-F50. 

INPUT-OUTPUT SECTION. 

FILE-CONTROL. 

I-O-CONTROL. 

DATA DIVISION. 

FILE SECTION. 

WORKING-STORAGE SECTION. 

LINKAGE SECTION. 

77 TRANS-COB PIC X(7). 

77 TRANS- ASSM PIC X(4). 

01 PASS-REC. 

05 FILLER PIC X. 

05 TRANS- VALUE PIC X. 

05 FILLER PIC X(78). 
PROCEDURE DIVISION USING TRANS-COB. 



GOBACK. 
B. ENTRY 'COBREGN1' USING PASS-REC. 



GOBACK. 
C. ENTRY 'COBREGN2' USING TRANS- ASSM. 



GOBACK. 

L , J 

Figure 78. Sample Calling and Called Programs (Part 5 of 6) 
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ASSMPGM START O 

PRINT NOGEN 
ENTRY ASSMRTN 

* 

USING ASSMRTN, 15 

* SAVE ROUTINE 



ASSMRTN 
* 

* 
* 
* 
* 
* 
* 
* 



SAVE (14,12) 



LR 10,15 
DROP 15 

USING ASSMRTN, 10 
LR 11,13 



AREA 

PROCESS 
* 

* 

* 
* 
* 
* 
* 
* 
* 



LA 



ST 



ST 

B 
DS 



13, AREA 



13,8(11) 



11,4(13) 

PROCESS 
18F 

2,0(1) 



ESTABLISHES ASSMRTN AS AN EXTERNAL NAME THAT CAN BE 
REFERRED TO IN ANOTHER PROGRAM. 



STORES THE CONTENTS OF REGISTERS 14, 15, 0, AND 1 
IN WORDS 4, 5, 6, AND 7 OF THE SAVE AREA. 
THESE ARE CONVENTIONAL LINKAGE REGISTERS. 
REGISTERS 2 THROUGH 12, WHICH ARE NOT 
ACTUALLY USED FOR LINKAGE, ARE SAVED IN SUBSEQUENT 
WORDS OF THE SAVE AREA. THE EXPANDED CODE OF THE 
SAVE MACRO INSTRUCTION USES REGISTER 13, WHICH 
CONTAINS THE ADDRESS OF THE SAVE AREA, IN 
EFFECTING THE STORAGE OF REGISTERS. 



LOADS THE ADDRESS OF THE SAVE AREA INTO REGISTER 11, 
WHICH WILL SUBSEQUENTLY BE USED TO REFER TO THE 
SAVE AREA. 

LOADS THE ADDRESS OF THIS PROGRAM' S SAVE AREA INTO 
REGISTER 13. 

STORES THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO 
WORD 3 OF THE SAVE AREA OF THE CALLING PROGRAM. 

STORES THE ADDRESS OF THE PREVIOUS SAVE AREA INTO 
WORD 2 OF THIS PROGRAM'S SAVE AREA. 

RESERVES 18 WORDS FOR THE SAVE AREA. 

LOADS INTO REGISTER 2 THE ADDRESS OF THE IDENTIFIER- 
LIST PASSED TO THE PROGRAM. THE ADDRESS OF THE 
IDENTIFIER-LIST IS ALWAYS PASSED IN REGISTER 1, 
WHICH IS USED HERE AS THE BASE REGISTER TO GET THE 
ADDRESS. SUBSEQUENT REFERENCES TO THE IDENTIFIER 
WILL USE REGISTER 2 AS THE BASE REGISTER FOR THAT 
ADDRESS. (IF A VARIABLE- LENGTH IDENTIFIER-LIST 
COULD BE USED IN CALLING THIS PROGRAM, EACH 
IDENTIFIER WOULD BE TESTED FOR A ONE IN THE 
HIGH-ORDER BIT. ) 



{User-written program statements} 



* CALLING SEQUENCE 

LA 1 , ARGLST 



CALL COBREGN2 



LOADS INTO REGISTER 1 THE ADDRESS OF THE IDENTIFIER- 
LIST TO BE PASSED. 

TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED 
PROGRAM. [THE CALL MACRO INSTRUCTION GENERATES 
CODING THAT LOADS A V-TYPE ADDRESS CONSTANT — 
COBREGN2 — INTO REGISTER 15 AND PLACES INTO 
REGISTER 14 THE RETURN ADDRESS (THAT IS, THE 
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION)]. 



{User-written program statements} 
Sample Calling and Called Programs (Part 6A of 6) 



Figure 71 
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* CALLING SEQUENCE 

LA 1 , ARGLST 



LOADS INTO REGISTER 1 
IDENTIFIER- 
LIST TO BE PASSED. 



THE ADDRESS OF THE 



CALL COBREGN2 



TRANSFERS CONTROL TO THE ENTRY POINT OF THE CALLED 
PROGRAM. [THE CALL MACRO INSTRUCTION GENERATES 
CODING THAT LOADS A V-TYPE ADDRESS CONSTANT — 
COBREGN2 — INTO REGISTER 15 AND PLACES INTO 
REGISTER 14 THE RETURN ADDRESS (THAT IS, THE 
ADDRESS OF THE FIRST BYTE FOLLOWING THE MACRO 
EXPANSION) ] . 



{User-written program statements} 



RETURN ROUTINE 

L 13,4(13) 



RETURN(14,12> ,T,RC=(15) 



PARAMETER LIST 





DS 


OF 


ARGLST 


DC 


X'80' 




DC 


AL3 (ARGUMENT) 


ARGUMENT 


DC 


C'l« 



LOADS THE ADDRESS OF THE PREVIOUS SAVE AREA 
BACK INTO REGISTER 13. 

THIS RETURN MACRO INSTRUCTION RESTORES THE SAVED 
REGISTERS (14, 15, AND THROUGH 12). THE RETURN 
ADDRESS IS RESTORED TO REGISTER 14, AND THE 
EXPANSION INCLUDES A BRANCH TO THAT INSTRUCTION. 
THE •T 1 IN THE RETURN MACRO INSTRUCTION CAUSES 
THE EIGHT HIGH-ORDER BITS OF WORD 4 OF THE SAVE 
AREA TO BE SET TO ONES AS AN INDICATION THAT THE 
RETURN HAS OCCURRED. THE RC=(15) PARAMETER 
INDICATES THAT THIS PROGRAM IS PASSING A RETURN 
CODE IN REGISTER 15. 



THIS PARAMETER LIST CONTAINS ONLY 1 ARGUMENT. 

FIRST BYTE OF LAST ARGUMENT (ONLY ARGUMENT IN 
THIS PROGRAM) SETS BIT TO 1. 



END 



Figure 78. Sample Calling and Called Programs (Part 6B of 6) 



LINK-EDITING PROGRAMS 



Each time an entry point is specified in 
a called program, an external nam e is 
defined (except when a program is compiled 
using the DYNAM and RESIDENT compiler 
options). An external name is a name that 
can be referred to by another separately 
compiled or assembled program. Each time 
an entry name is specified in a calling 
program, an exter n al reference is defined 
except when a program is compiled using the 
DYNAM and RESIDENT compiler options. An 
external reference is a symbol that is 
defined as an external name in another 
separately compiled or assembled program. 
The linkage editor resolves external names 
and references and combines calling and 
called programs into a format suitable for 
execution together, i.e., as a single load 
module except when programs are compiled 
with dynamic CALL statements and/or the 
RESIDENT option (see the section entitled 
"Programs Compiled with the DYNAM and/or 
RESIDENT Options"). 



Load modules of both calling and called 
programs are used as input to the linkage 
editor. There are two kinds of input, 
primary and additional. Primary input 
consists of a sequential data set that 
contains one or more separately compiled 
object modules and/or linkage editor 
control statements. The primary input can 
contain object modules that are either 
calling or called programs or both. 
Additional input consists of object modules 
or load modules that are not part of the 
primary input data set but are to be 
included in the load module. The 
additional input may be in the form of (1) 
a sequential data set consisting of one or 
more object modules with or without linkage 
editor control statements, or (2) libraries 
containing object modules with or without 
linkage editor control statements, or (3) 
libraries consisting of load modules. Note 
that the secondary input (all libraries 
and/or data sets) must be composed of 
either all object modules or all load 
modules, but it cannot contain both types. 
The additional input is specified by 
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Word 
No. 


Area 
No. 




1 
2 


AREA 
AREA 


+ 4 



18 



AREA +8 



Contents 
-I 

Used by COBOL. 

Address (passed by the calling program) of the save area used by the 
calling program. This is the address of a save area that was 
passed to the called program by the program that called the called 
program. 

Address (stored by the called program) of the next save area, that 
is, the save area that the called program provides for a program 
that it calls. The called program need not reserve a save area if 
it does not, in turn, call another program. 

AREA +12 Return address (contents of register 14) stored by the called 
program. 

AREA +16 Entry point address (contents of register 15) stored by the called 
program. 

AREA +20 Contents of register (stored by the called program). 

AREA +24 Contents of register 1 (stored by the called program) ; that is, the 
address of the identifier list passed to the called program. 



AREA +28 



Contents of registers 2 through 12 (stored by the called program). 



AREA +68 
Figure 79. Save Area Layout and Contents 






linkage editor control statements in the 
primary input and a DD statement for each 
additional input data set. Additional 
input may contain either calling or called 
programs or both. 

Note : Each additional input data set may 
itself contain external references or names 
and linkage editor control statements that 
specify more additional input. 



SPECIFYING PRIMARY INPUT 



The primary input data set is specified 
for linkage editor processing by the SYSLIN 
DD statement. The linkage editor must 
always have a primary input data set 
specified by a SYSLIN DD statement whether 
or not there are called or calling programs 
and even if the primary input data set 
contains only linkage editor control 
statements. The SYSLIN DD statement that 
specifies the primary input is discussed in 
"Linkage Editor Data Set Requirements" (see 
"Example of Linkage Editor Processing" for 
a discussion of how to specify a primary 
input data set that contains more than one 
object module along with linkage editor 
control statements). 



SPECIFYING ADDITIONAL INPUT 



Additional input data sets are specified 
by linkage editor control statements and a 
DD statement for each additional input data 
set. 



The linkage editor control statements 
that specify additional input are INCLUDE 
and LIBRARY. x A primary input data set may 
consist entirely of such statements. The 
INCLUDE and LIBRARY statements may be 
placed before, between, or after object 
modules or other control statements in 
either primary or additional input data 
sets. One method of using these statements 
is shown in Figure 87. 



Note : Additional input often contains 
members of libraries (see "Specifying 
Libraries as Additional Input" in 
"Libraries") . 



i-The operation field in a linkage editor 
control statement must start after column 
1. The operand field must be preceded by 
at least one blank. 
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INCLUDE Statement 



ALIAS Statement 



The INCLUDE statement is used to include 
an additional input data set that is either 
a member of a library or a sequential data 
set. Its format is: 



r t 

| Operation | Operand 
j. 



| INCLUDE | 

I I 

I I 

I I 

L X. 



ddname [ (member- name 
[ , member-name] . . . ) ] 
[ , ddname [ ( member-name 
[ , member-name. ..])]].. 



where ddname indicates the name of the DD 
statement that specifies the library or 
sequential data set, and member-name is the 
name of the library member that is to be 
included. Member-name is not used when the 
additional input data set is not a member 
of a partitioned data set. 



LIBRARY Statement 



The LIBRARY statement is used to include 
additional input that may be required to 
resolve external references. 



The ALIAS statement specifies additional 
names for the output library member, and 
can also display names of additional entry 
points. If a load module has more than one 
entry point or more than one CSECT and the 
user wishes to access that alternate entry 
at execution time via a dynamic CALL, he 
should specify an ALIAS with the same 
symbolic name as the desired entry point or 
CSECT. 



r t 

(Operation | Operand 



ALIAS 



j (symbol 



j (external name 
.x 



', symool 

, external name 



where symbol specifies an alternate name 
for the load module, and external name 
specifies a name that is defined as a 
control section name in the output module. 

If the linkage-editor input includes an 
ALIAS statement, the symbolic name 
specified is identified with the relative 
location of the entry point or CSECT name 
that matches the ALIAS. If there is no 
matching entry point or CSECT name, the 
ALIAS is identified with relative location 
zero in the load module. 



NAME Statement 



The format is: 



r t 

| Operation | Operand 

I- 



| LIBRARY | 

I I 

I I 

I I 

L X. 



ddname ( member-name 
t , member-name] . . . ) 
[ , ddname ( member-name 
[ , member-name. ..])].. 



where ddname indicates the name of the DD 
statement that specifies the library, and 
member-name is the name of the member of 
the library. 

The LIBRARY statement differs from the 
INCLUDE statement in that libraries 
specified in the LIBRARY statement are not 
searched for additional input until all 
other processing, except references 
reserved for the automatic library call, is 
completed by the linkage editor. Any 
additional module specified by an INCLUDE 
statement is incorporated immediately, 
whenever the INCLUDE statement is 
encountered. 



The NAME statement specifies the name of 
the load module created from the preceding 
input modules, and serves as a delimiter 
for input modules, and serves as a 
delimiter for input to the load module. 
The NAME statement may be used to assign a 
symbolic name to a load module. This 
symbolic name is entered in the directory 
of the partitioned data set that contains 
the module, and allows the module to be 
accessed at execution time by an OS LOAD 
macro. A Load module name is always 
associated with relative location zero in 
the load module. 

r t i 

| Operation | Operand | 

j. x ., 

| NAME | member-name [(R)] | 

L x J 

where member-name specifies the name to be 
assigned to the load module that is created 
from the preceding input modules, and (R) 
indicates that this load module replaces an 
identically named module in the input 
module library. (If the module is not a 
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replacement, the parenthesized value (R) 
should not be specified. ) 

If the linkage-editor input includes a 
NAME statement, the symbolic name specified 
is always identified with relative location 
zero in the load module. 



module form in a library that is available 
to the system at execution time. 

The link-editing that takes place varies 
with the combinations of the DYNAM( NODYNAM) 
and RESIDENT (NORESIDENT) options in effect. 
What would seem to be the most 
representative link-edit situations are 
discussed in the sections that follow. 



PROGRAMS COMPILED WITH THE DYNAM AND/OR 
RESIDENT OPTIONS 



§E§cifyin£_DYNAJVRESIDENT 



In the usual called/ calling situation, 
all references to any subprogram or library 
subroutines generated in an object program 
result in a V-type address constant (VCON) 
that must be resolved by the linkage 
editor. Therefore, at link-edit time, the 
modules referred to by VCONs are made a 
part of a single load module containing the 
object program and all reguired subprograms 
and library routines. When the object 
program is executed, all those reguired 
routines are present in the user region for 
the entire execution step, even though they 
may have been used only at the beginning of 
the main program and never invoked again. 
With dynamic linkage, on the other hand, 
the user can invoke a called program when 
it is needed and retain it for only the 
per iod .. needed, _ 

Subprograms invoked through the CALL 
literal statement are dynamically loaded 
using the Operating System LOAD macro if 
DYNAM is specified. Before the CALL 
Subprogram is executed, linkage is effected 
for all COBOL library subroutines reguired 
by the subprogram. Similarly, use of the 
CANCEL statement makes it possible to 
dynamically delete subprograms at object 
time. 

Figure 76 earlier in this chapter is an 
example of a job compiled with the DYNAM 
and RESIDENT options. Figures 80 through 
8 3 in this section illustrate for 
called/calling programs the relationship 
between the possible combinations of the 
DYNAM/RESIDENT options and the identifier 
and literal options of the CALL and CANCEL 
statements. Figure 84 shows the JCL 
necessary for compiling, link-editing, and 
executing a calling COBOL program and a 
called COBOL program when both of the 
programs invoke the DYNAM and RESIDENT 
compiler options. 

When a program is compiled with DYNAM 
and RESIDENT, no external references are 
generated. Therefore, while the program 
may refer to other modules, no references 
are resolved by the linkage editor. In 
such a case, the only input to the linkage 
editor is the program itself. Any module 
the program refers to must exist in load 



When both DYNAM and RESIDENT are 
specified for the called/calling situation 
pictured in Figure 78, first the main 
program COBA is compiled and link-edited; 
then each of the two subprograms COBB and 
COBC is compiled and link-edited 
separately, thereby producing three 
modules. Then the main program is 
executed. 

In this situation, all external 
references are dynamically resolved. 
Therefore, no VCONs are generated for the 
address of an external symbol that would be 
used in a static situation (that is, a CALL 
literal without the DYNAM option) to effect 
branches to other programs. 



r 1 

| | CALL 

| COBA I- 

| | literal 

L J 



r 1 r 1 

I I CALL | | 

> | COBB I- > | COBC | 

| | literal | | 

L J L J 



Figure 80. CALL with DYNAM and RESIDENT 



Speci fying NODYNAM/RESIDENT 



When NODYNAM and RESIDENT are specified 
for the called/calling situation pictured 
in Figure 81, a dynamic situation occurs 
because of the inclusion of CALL identifier 
in the calling programs. That is, because 
the name of the called subprogram is not 
available until execution time, a CALL 
identifier statement cannot be used in a 
static situation. 

Moreover, when NODYNAM and NORESIDENT 
are either specified or implied by default, 
and a CALL identifier or CANCEL identifier 
statement occurs in the source program 
being compiled, the Library Management 
Feature is automatically in effect. 

Notes A printed indication of the compiler 
options in effect appears in the statistics 
section of the compiler output. (For 
examples of compiler statistics, see the 
chapter entitled "Output.") 
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r 1 r 1 r 1 

J | CALL | | CALL j | 

I COBA J- > J COBB (- > J COBC | 

j j identifier J j identifier j j 

L_, .J L J L J 

Figure 81. CALL With NODYNAM and RESIDENT 

In contrast with Figure 81, the 
called/calling situation pictured in Figure 
82 invokes the CALL literal option. Again 
the programs are compiled in the order 
COBA, COBB, and COBC. The CALL literal 
statements included in programs COBA and 
COBB result in static calls that must be 
resolved by the linkage editor. However, 
with the COBOL Library Management Feature 
in effect, linkage to the library is 
dynamic. That is, the required COBOL 
object-time library subroutines are not 
link-edited, but linkage is effected 
dynamically at object time. 

Note : When including both dynamic and 
static CALL statements in the same run 
unit, the programmer should not dynamically 
call any subprograms that are otherwise 
called statically. To do so might cause 
multiple copies of the called program to be 
created and, therefore, produce 
unpredictable results. 



CALL CALL 
literal > literal > 



COBA 



"T 

I 

| COBB 

I 
.X 



COBC 



Specifying NO DYNAM/NORESIDE NT 



For the called/calling situation 
pictured in Figure 83, the COBOL Library 
Management Feature is not in effect, and 
all CALL statements result in static calls 
that must be resolved by the linkage 
editor. One load module is produced for 
the programs COBA, COBB, COBC, and all of 
the necessary COBOL library subroutines. 



The NODYNAM/NORESIDENT set of options 
should be used only when the user does not 
intend to use the CALL or CANCEL identifier 
statement or the Library Management 
Feature. If either a CALL identifier or a 
CANCEL identifier statement appears in any 
one program, the Library Management Feature 
is in effect for that program only. This 
situation may result in a duplication of 
subprograms and COBOL library subroutines 
within the user region/partition, thereby 
causing unpredictable results. 



COBA 



COBB 



COBC 



T T- 

| COBOL Library Subroutines! 
l J 



Figure 83. CALL With NODYNAM and 
NONRESIDENT 



Figure 8 2. CALL With NODYNAM and RESIDENT 
With CALL Literal Option 
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//JOBY 
//STEP1 



//SYSLIN 
//SYSIN 



/* 

//STEP2 
//SYSLMOD 
//SYSLIN 
//SYSIN 

NAME 
/* 

//STEP3 
//SYSLIN 
//SYSIN 



/* 

//STEP4 
//SYSLMOD 
//SYSLIN 
//SYSIN 

NAME 
/* 
//STEP5 

}//STEPLIB 

|/* 



JOB 

EXEC PGM=IKFCBL00, PARM=' LOAD, DYNAM, RESIDENT 1 



DD 
DD 



DSNAME=S6LINKDS1, DISP= (MOD, PASS) , UNIT=SYSSQ 

* 



{Source module for COBMAIN, a calling COBOL program} 

CALL 'COBSUB' 

EXEC PGM=IEWL 

DD DSNAME=S&GOFILE, DISP=(MOD, PASS) , UNIT=SYSSQ 

DD DSNAME=£SLINKDSl, DISP= ( OLD, DELETE) , UNIT=SYSSQ 

DD * 

COBMAIN 

EXEC PGM=IKFCBL00, PARM=LOAD, DYNAM, RESIDENT 

DD DSNAME=S€LINKDS2, DISP= (MOD, PASS) , UNIT=SYSSQ 

DD * 

{Source module for COBSUB, a called COBOL program} 

EXEC PGM=IEWL 

DD DSNAME=&SGOFILE,DISP= (MOD, PASS), UNIT=SYSSQ 

DD DSNAME=SSLINKDS2, DISP= (OLD, DELETE) , UNIT=SYSSQ 

DD * 

COBSUB 

EXEC PGM=COBMAIN 

DD- DS&AMX-&&GOFILE, D-ISP= <QLD r DEL£TE) , UNIT^SYSSO^ 



Figure 84. Sample JCL for Called/Calling Programs Compiled with the DYNAM and RESIDENT 
Options 
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ENTRY ASSMRTN 



* SAVE ROUTINE 
ASSMRTN SAVE (14,12) 

* 
* 
* 
* 
* 
* 
* 
* 



LR 



11,13 



LA 13, AREA 
13, 8(11) 



ST 



ST 



11,4(13) 



AREA 



DS 



18F'0' 



RETURN ROUTINE 

L 13,4(13) 



RETURNU4, 12) , T, RC=(15> 



ESTABLISHES ASSMRTN AS AN EXTERNAL NAME THAT 
REFERRED TO IN ANOTHER PROGRAM. 



:an BE 



STORES THE CONTENTS OF REGISTERS 14, 15, 0, AND 1 
IN WORDS 4, 5, 6, AND 7 OF THE SAVE AREA. THESE 
ARE CONVENTIONAL LINKAGE REGISTERS. REGISTERS 2 
THROUGH 12, WHICH ARE NOT ACTUALLY USED FOR 
LINKAGE, ARE SAVED IN SUBSEQUENT WORDS OF THE SAVE 
AREA. THE EXPANDED CODE OF THE SAVE MACRO 
INSTRUCTION USES REGISTER 13, WHICH CONTAINS THE 
ADDRESS OF THE SAVE AREA, IN EFFECTING THE STORAGE 
OF REGISTERS. 

LOADS THE ADDRESS OF THE SAVE AREA INTO REGISTER 11, 
WHICH WILL SUBSEQUENTLY BE USED TO REFER TO THE 
SAVE AREA. 

LOADS THE ADDRESS OF THIS PROGRAM'S SAVE AREA INTO 
REGISTER 13. 

STORES THE ADDRESS OF THIS PROGRAM' S SAVE AREA 
INTO WORD 3 OF THE SAVE AREA OF THE CALLING 
PROGRAM. 

STORES THE ADDRESS OF THE PREVIOUS SAVE AREA INTO 
WORD 2 OF THIS PROGRAM'S SAVE AREA 



RESERVES 18 WORDS FOR THE SAVE AREA AND 
INITIALIZES THEM TO ZERO. 



LOADS THE ADDRESS OF THE PREVIOUS SAVE AREA BACK 
INTO REGISTER 13. 

THIS RETURN MACRO INSTRUCTION RESTORES THE SAVED 
REGISTERS (14, 15, AND THROUGH 12). THE RETURN 
ADDRESS IS RESTORED TO REGISTER 14, AND THE 
EXPANSION INCLUDES A BRANCH TO THAT INSTRUCTION. 
THE « T' IN THE RETURN MACRO INSTRUCTION CAUSES THE 
EIGHT HIGH-ORDER BITS OF WORD 4 OF THE SAVE AREA 
TO BE SET TO ONES AS AN INDICATION THAT THE RETURN 
HAS OCCURRED. THE RC=(15) PARAMETER INDICAIES 
THAT THIS PROGRAM IS PASSING A RETURN CODE IN 
REGISTER 15; THIS VALUE SHOULD BE SET TO ZERO 
IF NONE IS WANTED. 



Not e: If the called program containing this coding did not call another program, it 
would not require a reserved save area (AREA) and the coding to store the save area's 
address. 

Figure 85. Sample Linkage Coding Used in a Called Assembler-Language Program that Calls 
Another Program 
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//CALLPROG 
//STEP1 



//SYSLIN 

// 

//SYSIN 

/* 

//STEP2 

// 

//SYSGO 

//SYSIN 



/* 

//STEP3 
// 



JOB 
EXEC 



PGM=IKFCBL00, PARM=(LOAD, NODECK) 



//PROGLIB1 


DD 


//SYSLIN 


DD 




INCLUDE 




ENTRY 


/* 




//STEP4 


EXEC 


// 


(5,LT,STE 


//SYSOUT 


DD 



DD DSN=£&TEMPLIBl, UNIT=SYSSQ, DISP= (NEW, PASS) , 
SPACE=(TRK, (10,1)) 

DD * 
(Source module for COBSUB, a called COBOL program) 

EXEC PGM=IEUASM, PARM= (LOAD, NODECK) , 

COND= ( 9 , LT, STEP1 ) * 

DD DSN=££TEMPLIB1. UNIT=SYSSO. DISP=(MOD. PASS) 
DD * 

(Source module for ASSMMAIN, a calling assembler- 
language program) 

EXEC PGM=IEWL f PARM=(LIST, XREF, LET) , 
COND= ( ( 9 , LT, STEP1 ) , ( 5 , LT, STEP2 ) ) 



DSN=6&TEMPLIBl, DISP=OLD 

* 

PROGLIB1 2 

ASSMMAIN 3 

PGM=*.STEP3.SYSLMOD,COND=( (9,LT,STEP1) , 
>), (5,LT,STEP3) ) 
SYSOUT=A 



^-This example was chosen to illustrate the testing of condition codes* 
2 See the discussion under the INCLUDE statement. 

3 Because the COBOL program is compiled first and the linkage editor cannot identify the 
proper entry point, the ENTRY statement must be included. 

L 

Figure 86. Sample Coding Used for a Calling Assembler-Language Program and a Called 
COBOL Program 



LINKAGE EDITOR PROCESSING 



The linkage editor first processes the 
primary input and any additional input 
specified by INCLUDE statements. All 
external references in the primary that 
refer only to other modules in the included 
input are resolved first. If there are 
still unresolved references after this 
input is processed, the automatic call 
library, which includes libraries specified 
by the SYSLIB DD statement and by the 
LIBRARY statements, is searched to resolve 
the references. The automatic call librar* 7 
generally will contain the COBOL library 



subroutines. (External references to these 
subroutines are generated by the COBOL 
compiler when statements in the source 
module require certain functions to be 
performed, such as some data conversions.) 

If the additional input contains 
external references and/or linkage editor 
control statements, the references are 
resolved in the same way. Data sets 
specified by the INCLUDE statement are 
incorporated when the statement is 
encountered. Data sets specified by the 
LIBRARY statement are used only when there 
are unresolved references after all of the 
other processing is completed. 
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//JOBX 
//STEP1 



//SYSLIN 
//SYSIN 



/* 
//STEP2 



//SYSLIN 
//SYSIN 



/* 

//STEP3 



//SYSLIN 
//SYSIN 



/* 

//STEP4 



//SYSLIB 

//SYSLMOD 

// 

//DBLIB 

//ADDLIB 

//SYSLIN 

// 



/* 
Figure 87. 



JOB 
EXEC 



DD 
DD 



PGM=IKFCBL00, PARM=LOAD 



DSNAME=&SGOFILE, DISP=(MOD, PASS) , UNIT=SYSSQ 

* 



(Source module for COBMAIN) 



EXEC 



DD 
DD 



PGM=IKFCBL00, PARM=LOAD 



DSNAME=*.STEP1. SYSLIN, DISP=( MOD, PASS) 

* 



(Source module for COBOL1) 



EXEC 



DD 
DD 



PGM=IKFCBL00, PARM=LOAD 



DSNAME=*. STEP2. SYSLIN, DISP= (MOD, PASS) 

* 



(Source module for COBOL1A) 



EXEC PGM=IEWL 



DD DSNAME=SYSl.COBLIB,DISP=OLD 

DD DSNAME=PGMLIB(CALPGM) ,DISP=NEW, UNIT=2311,SPACE= X 

(1024, (50,20,2) ) , VOLUME=SER=LIBPAK 

DD DSNAME=DBJLIB, DISP=OLD 

DD DSNAME=MYLIB,DISP=OLD 

DD DSNAME=&&GOFILE,DISP= (OLD, DELETE) X 

DD * 

INCLUDE DBLIB (COBOLlB, RSSMPGM) 

LIBRARY ADDLIB (COBREGNO) 



Specifying Primary and Additional Input to the Linkage Editor 



Example of Linkage Editor Processi ng 



Figure 87 shows the control statements 
for a job that separately compiles three 
source modules (one is a calling program 
and two are called programs) and places 
them in one data set as primary input for 
the linkage editor. The linkage editor 
then links them together with additional 
input (called programs that are members of 
the specified libraries) to form one load 
module. 



STEP1 compiles a source module called 
COBMAIN, STEP2 compiles a source module 
called COBOL1, and STEP3 compiles a source 
module called COBOL1A. The object module 
from each step is placed in the sequential 
data set called &&GOFILE. (Since MOD and 
PASS are specified for 6&GOFILE in the 
SYSLIN DD statement in STEP1, the object 
modules COBOLl and C0BOL1A are placed in 
the data set behind the object module 
COBMAIN. ) 

In STEP4, the linkage editor uses the 
SSGOFILE data set as primary input, and the 
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cataloged libraries MYLIB, OBJLIB, and 
SYS1.COBLIB as additional input. (The 
INCLUDE and LIBRARY statements become part 
of the primary input through the DD * 
statement following the SYSLIN DD 
statement. 

The object modules of the data set 
SgGOFILE and the members C0B0L1B and 
ASSMPGM of OBJLIB are processed first. If 
there are unresolved references after this 
input is processed, the linkage editor 
searches the automatic call library, which 
includes the COBOL subroutine library and 
member COBREGNO of MYLIB, to resolve these 
references. OBJLIB is specified in the 
OBLIB DD statement and MYLIB in the ADDLIB 
DD statement. 

After linkage editor processing is 
completed, a new library, PGMLIB, is 
created with CALPGM as a member. CALPGM 
contains COBMAIN, C0B0L1, COBOL1A, C0B0L1B, 
ASSMPGM, and, possibly, COBOL subroutines 
and COBREGNO. 



must be link-edited together to form one 
module 42,000 bytes in size. Therefore, 
COBMAIN would require 42, 000 bytes of 
storage in order to be executed. 

If the subprograms needed do not fit 
into main storage, the following three 
techniques of overlay are available to the 
COBOL programmer: 

• Preplanned overlay using the linkage 
editor 

• Dynamic overlay using macro 
instructions during execution 

• Segmentation Feature 

Note : The largest load module that can be 
processed by Fetch is 524,248 bytes. If a 
load module exceeds this limit, it should 
be divided. 



Lin ka ge Editing with Preplanned Overlay 



OVERLAY STRUCTURES 



If the called programs needed to execute 

..ojae...CDJBQL_.s^iirx^.^r^gxam..d.Q_nQt_aJJ^fi.t. 

into main storage at the same time, it is 
still possible to use them with the overlay 
technique or with the use of the 
segmentation feature. Called programs that 
do not need to be in main storage at the 
same time can be given the same relative 
storage address and then loaded at 
different times during execution when they 
are needed. In this way, the same storage 
space can be used for more than one called 
program. The use of segmentation is 
discussed in "Using the Segmentation 
Feature. " 



Considerations for Overlay 



Assume that the six programs illustrated 
in Figure 78 have the following load module 
sizes: 



j Program j Module Size (in Bytes) j 



COBMAIN 

COBOL1 

COBOL1A 

COBOL1B 

COBREGNO 

ASSMPGM 



11,000 
4,000 
6,000 
5,000 
3,000 

13,000 



-I 



Through the linkage mechanism, CALL 
COBOL1..., all subprograms plus COBMAIN 



The preplanned linkage editor facility 
permits the reuse of storage locations 
already occupied. By judiciously 
modularizing a program and using the 
_ Linkage. ...editor. „_Q„verl_ay f_aciiity^.._a._pro_grairL.. 
that is too large to fit into storage at 
one time can be executed. 

In using the preplanned overlay 
technique, the programmer specifies to the 
linkage editor which subprograms are to 
overlay each other. The subprograms 
specified are processed as part of the 
program by the linkage editor, so they can 
be automatically placed in main storage for 
execution when requested by the program. 
The resulting output of the linkage editor 
is called an overlay structure. 

It is possible, at linkage edit time, to 
set up an overlay structure by using the 
COBOL source language linkage statement and 
the linkage editor OVERLAY statement. 
These statements enable a user to call a 
subprogram that is not actually in storage 
The details for setting up the linkage 
editor control statements for accomplishing 
this procedure can be found in the 
publi ca tion IBM OS Linkage Ed itor a nd 
Loader . 

In a linkage editor run, the programmer 
specifies the overlay points in a program 
by using OVERLAY statements. The linkage 
editor treats the entire input as one 
program, resolving all symbols and 
inserting tables into the program. These 
tables are used by the control program to 
bring the overlay subprograms into storage 
automatically when called. 
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I 

Root Segment 1 

JCOBMAIN ) 

I COBREGNO f 

I 

I 

I 
J. 



ALPHA 



Segment 2 
{COBOL1} 



Segment 5 
{ASSMPGM} 



J. 

BETA 



Segment 3 
{COBOL1A} 



Segment 4 
{COBOL1B} 



_JL_ 



Figure 88. Overlay Tree Structure 



Figure 88 is an overlay tree structure 
illustrating how the six programs in Figure 
78 could be positioned in core at execution 
time using preplanned linkage editor 
overlay. 

Figure 89 shows the deck arrangement 
required to achieve the overlay illustrated 
in Figure 88. The OVERLAY statements 
specify to the linkage editor that the 
overlay structure to be established is one 
in which the called programs of COBOL1 
(C0B0L1A and COBOL1B) overlay each other 
when called for execution, and that ASSMPGM 
and COBOL1 and its called program overlay 
each other when called. 



Routine COBREGNO is placed with COBMAIN 
in the root segment of the overlay 
structure because it is called by three of 
the routines in the program, the largest of 
which is ASSMPGM. Utilizing COBREGNO as an 
individual overlay segment would not have 
resulted in a net decrease in the amount of 
core required for execution because the 
minimum amount of core needed would have to 
contain COBMAIN, ASSMPGM, and COBREGNO at 
the same time. Creating another overlay 
segment for COBREGNO would only have added 
to the amount of time required for program 
execution. 
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//OVERLAY 

//STEP1 

//SYSLIB 

//SYSPRINT 

//SYSUT1 

//SYSLMOD 

// 

//SYSLIN 



JOB 

EXEC 

DD 

DD 

DD 

DD 

DD 



{COBMAIN 
{COBREGNO 

OVERLAY ALPHA 

CCOBOL1 



OVERLAY BETA 

CCOBOL1A 

OVERLAY BETA 

{COBOL1B 

OVERLAY ALPHA 

{ASSMPGM 
/* 



NY83937800, COSMO, MSGLEVEL=1 

PGM=IEWL, PARM=' OVLY, LIST, XREF, LET* 

DSNAME=SYS1. COBLIB, DISP=SHR 

SYSOUT=A 

UNIT=SYSDA, SPACE=(1024, (50,20)) 

DSNAME=6GODATA(RUN) , DISP= (NEW, PASS) , UNIT=SYSDA, X 

SPACE=(1024, (50,20,1)) 

* 

object deck} 
object deck} 



object deck} 
object deck} 
object deck} 
object deck} 
Figure 8 9. Sample Deck for Linkage-Editor Overlay Structure 



D yna m ic Overlay Tech n ique 



in preparation for the dynamic overlay 
technique, each part of the program brought 
into storage independently should be 
processed separately by the linkage editor. 
(Hence, each part must be processed as a 
separate load module. ) To execute the 
entire program, the programmer must: 

1. Specify the main program in the EXEC 
statement. 

2. Bring the separately processed load 
modules into storage when they are 
required, by using the appropriate 
supervisor linkage macro instructions. 
This is accomplished during execution. 



The dynamic overlay technique can be 
used to overlay subprograms during 
execution. To accomplish dynamic overlay 
of subprograms, the programmer must write 
an assembler language subprogram that 
employs the LINK macro instruction to call 
each COBOL subprogram. For a detailed 
description of the LINK macro instruction, 
see the publication IB M OS; Supervisor and 
D ata M anagement Macro Instruction s. 



In using the dynamic overlay technique, 
the main program communicates with the 
assembler language subprogram by using the 
COBOL language CALL statement. The CALL 
statement can be used to pass the name of 
the COBOL subprogram (to be linked) and the 



specified parameter list to the assembler 
language subprogram. This procedure is the 
same for each CALL used in the main 
program. Hence, each CALL results in 
linking with a subprogram through the 
assembler language subprogram. 



When the COBOL subprogram is finished 
executing, it returns control to the 
assembler language subprogram, which in 
turn returns to the main program. The 
process is repeated for each CALL to the 
assembler-language subprogram. 



Dynamic overlay requires that a 
programmer have detailed knowledge of the 
linkage conventions, assembler language, 
and the LINK macro instruction with its 
features and restrictions. 

Figure 90 contains an example of a COBOL 
main program, PROGMAST, and an assembler 
language subprogram, LINKRTN. The two 
programs are link-edited together as a 
single load module. At execution time, the 
assembler-language subprogram dynamically 
fetches COBOL subprograms (OPN, BILL, CRDT 
TRNF, and LCK, none of which are shown in 
the example) for the main program using the 
LINK macro instruction. The COBOL 
subprograms are stored in a private 
library, DYNLINK. 

The parameter list passed to LINKRTN 
contains three identifiers, IRANS-REC, 
COM-WORD, and SWITCH, two of which 
(TRANS-REC and SWITCH) are reference! by 
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LINKRTN, and two of which (TRANS-REC and 
COM- WORD) are referenced by the COBOL 
subprograms fetched. LINKRTN passes the 
same parameter list it receives to the 
COBOL subprograms fetched. 

LINKRTN determines from identifier 
TRANS-REC which subprograms to fetch, and 
from SWITCH when to open and close the 
library DYNLINK. 

Note : In structuring a program with either 
the preplanned overlay technique or the 
dynamic overlay technique, special 
consideration must be given to the presence 
of the TRANSFORM table and the class test 
tables, which are members of the COBOL 
object-time library (see "Appendix B: 
COBOL Library Subroutines"). The TRANSFORM 
table is link-edited with a COBOL program 
if the TRANSFORM statement is used. 
Similarly, one or more of the class test 
tables is present in a COBOL load module if 



a class test is performed or if the OCCURS 
DEPENDING ON option is used. 



For these tables, which contain no 
executable code and are not branched to but 
are merely referenced, the compiler 
designates A-type address constants 
(ADCONs) and EXTRN references, rather than 
V-type address constants (VCONsJ. 
Accordingly, the overlay structure segment 
containing the tablets ) must be either the 
root segment or a segment that is higher in 
the same leg as the segment containing the 
reference(s) to the table(s). This 
requirement has no effect on the COBOL 
segmentation feature (see the chapter 
entitled "Use of the Segmentation 
Feature"), since (1) all members of the 
object-time subroutine library are 
link-edited into the root segment, and 
(2) American National Standard COBOL 
subprograms may not be segmented. 
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r- 



IDENTIFICATION DIVISION. 
PROGRAM-ID. PROGMAST. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. IBM-360-F50. 
OBJECT-COMPUTER. IBM-360-F50. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-Y ASSIGN TO UR-2540R-S-INFILE, 
I-O-CONTROL. 
DATA DIVISION. 
FILE SECTION. 

RECORD CONTAINS 80 CHARACTERS 

LABEL RECORD IS OMITTED. 
01 TRANS-REC. 

05 ACCOUNT-NUMBER PIC 9(10). 

05 TRANSACTION PIC 9(4). 

05 NAME PIC X(20). 

05 LOCATION PIC X(20). 

05 METER- READING PIC 9(6). 

05 DATE PIC 9(6). 

05 FILLER PIC X(8). 

05 AMOUNT PIC 9(6). 
WORKING- STORAGE SECTION. 
77 COM-WORD PIC X(12). 
77 SWITCH PIC 9 VALUE ZERO. 
PROCEDURE DIVISION. 



OPES" INPUT" FILE-Y. 

B. READ FILE-Y AT END GO TO END-RUN. 

C. CALL *GETUM* USING TRANS-REC COM-WORD SWITCH. 



END-RUN. CLOSE FILE-Y. 
MOVE 2 TO SWITCH, 
PERFORM C. 
STOP RUN. 



Figure 90. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technique (Part 1 of 3) 
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LINKRTN 



GETUM 



START 
PRINT NOGEN 
ENTRY GETUM 



SAVEAREA DS 



OPENLIB 



USING 


GETUM, 15 


SAVE 


(14,12) 


LR 


10,15 


DROP 


15 


USING 


GETUM, 10 


LR 


11,13 


LA 


13, SAVEAREA 


ST 


13,8(11) 


ST 


11,4(13) 


L 


5,0(1) 


USING 


PARAMLST, 5 


B 


OPENLIB 


DS 


18F 


L 


6,8(1) 


CLI 


0(6), C'l' 


BE 


INITREG 



BH CLOSLIB 
OPEN (DYNLINK) 
01 0(6), C'l' 
TABLE LOOK-UP ROUTINE 



INITREG 


LA 


2,RTNLST 




LA 


3,6 


FTNDRTN 


CLC 


TRANSACT, 0(2) 




BE 


GETRTN 




LA 


2,12(0, 2) 




BCT 


3,FINDRTN 




MVC 


ERRMSG+28 ( 4) , TRANSACT 


ERRMSG 


WTO 


' INVALID TRANSACTION' 


EXIT 


L 


13,4(13) 




SR 


15,15 



RETURN(14,12) ,T,RC=(15) 



DYNAMIC OVERLAY ROUTINE 



GETRTN 



L 1,24(11) 
LA 4,4(0,2) 
LINK EPLOC= ( 4 ) , DCB=DYNLINK 



EXIT 



UPON ENTRY TO THIS PROGRAM, REGISTER 1 POINTS 
TO A FIXED-LENGTH PARAMETER LIST OF THREE 
WORDS. 
THE FIRST WORD CONTAINS THE ADDRESS OF 

RECORD TRANS- REC. 
THE SECOND WORD CONTAINS THE ADDRESS OF 
COM-WORD, TO WHICH THIS PROGRAM DOES NOT 
REFER BUT WHICH IS USED BY ROUTINES THIS 
PROGRAM LATER LINKS TO. 
THE THIRD WORD CONTAINS THE ADDRESS OF 

SWITCH USED BY THIS PROGRAM TO CHECK THE 
STATUS OF THE PRIVATE LIBRARY DYNLINK 



REGISTER 5 LOADED WITH ADDRESS OF TRANS- REC 
REGTER 5 IS USED AS THE BASE REGISTER TO 
REFERENCE TRANS- REC. 



REGISTER 6 LOADED WITH ADDRESS OF SWITCH. 

CHECK SWITCH STATUS. 

IF SWITCH = 1, DYNLINK IS ALREADY OPEN; 

INITIALIZE REGISTERS. 
IF SWITCH > 1, DYNLINK IS NO LONGER NEEDED; 

CLOSE DYNLINK. 
IF SWITCH = THE FIRST TIME THROUGH, OPEN 

DYNLINK. 
SET SWITCH SO THAT OPEN IS BYPASSED ON FUTURE 

ENTRY. 



INITIALIZE REGISTERS 2 AND 3 FOR LOOK-UP. 

TRANSACT CONTAINS THE TRANSACTION CODE THAT 
DETERMINES WHICH ROUTINE TO FETCH. 



PRODUCE ERROR MESSAGE IF TRANSACT CONTAINS 
AN INVALID CODE. 

SET REGISTER 15 TO ZERO. 

THE RC=(15) PARAMETER INDICATES THAT THIS 

PROGRAM IS PASSING A RETURN CODE IN REGISTER 

15. 



RESTORE REGISTER 1 TO ORIGINAL STATUS. 

PASS REGISTER 4 TO NAME OF ROUTINE TO BE 
FETCHED. HAVE THE CONTROL PROGRAM 
FETCH THE ROUTINE POINTED TO BY 
REGISTER 4 FROM PRIVATE LIBRARY DYNLINK. 



Figure 90. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technique (Part 2 of 3) 
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CLOSLIB 


CLOSE 


(DYNLINK) 




B 


EXIT 




DS 


OF 


RTNLST 
* 


EQU 


* 


* 
* 








DC 


C« 0100* 




DC 


CL8'OPN' 




DC 


C» 0200* 




DC 


CL8'BILL' 




DC 


C^BOO* 




DC 


CLS'CRDT' 




DC 


C« 0400' 




DC 


CL8*TRNF' 




DC 


cosoo' 




DC 


CL8'LCK' 


DYNLINK 


EQU 


* 


* 


DCB 


DDNAME=SY 


PARAMLST 
* 


DSECT 




* 

TRANS REC 


DS 


0CL80 


ACCTNUM 


DS 


CLIO 


TRANSACT 


DS 


CL4 


NAME 


DS 


CL20 


LOCATION 


DS 


CL20 


METERRD 


DS 


CL6 


DATE 


DS 


CL6 




DS 


CL8 


AMOUNT 


DS 
END 


CL6 



CLOSE PRIVATE LIBRARY. 



AS THE TABLE SEARCHED BY THE TABLE LOOK-UP 

ROUTINE, RTNLST CONTAINS A LIST OF ALL VALID 
TRANSACTION CODES AND THE NAMES OF THE 
ROUTINES FETCHED TO HANDLE THE TRANSACTIONS 

TRANSACTION CODE 

ROUTINE NAME ASSOCIATED WITH ABOVE TRANSACTION 



DCB TO DEFINE PRIVATE LIBRARY REFERRED TO IN 
LINK MACRO INSTRUCTION. 

DSECT USED BY REGISTER 5 TO REFER TO TRANS- 
REC. THE RECORD DESCRIPTION CORRESPONDS TO 
THAT OF TRANS-REC IN PROGMAST. 



Not e; Had a job or step library (requiring either a JOBLIB or STEPLIB DD statement in 
the job control for execution of the main program) been used instead of a private 
library (which for this example requires a DD statement named DYNLNKDD) , responsibility 
for the opening and closing of the library would have been with the control program and 
not with LNKRTN. 

The use of a private library reduces to a minimum the amount of search time needed 
to retrieve member modules from a library. 

l 

Figure 90. Sample COBOL Main Program and Assembler-Language Subprogram Using Dynamic 
Overlay Technique (Part 3 of 3) 
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LOADING PROGRAMS 



SPECIFYING PRIMARY INPUT 



The loader resolves external names and 
references and combines calling and called 
programs into a format suitable for 
execution as a single load module. For 
information on invoking the loader, see 
"Using the Cataloged Procedures." 



When the dynamic call is used, all 
subprograms to be called dynamically must 
have been processed by the linkage editor. 
The loader may be used only to resolve 
references to subprograms invoked by static 
calls. Otherwise, load modules of both 
calling and called programs are used as 
input to the loader. There are two kinds 
of input, primary and additional. Primary 
input consists of one or more separately 
compiled object modules and/or load 
modules. Additional input consists of 
object modules or load modules that are not 
part of primary input data sets but are to 
be included in the load module. The 
additional input may be in the form of 

(1) libraries containing object modules, or 

(2) libraries containing load modules. 
Additional input may contain either calling 
or called programs or both. 



The primary input data set is specified 
for loader processing by the SYSLIN DD 
statement. The loader must always have a 
primary input data set whether or not there 
are calling or called programs. The SYSLIN 
DD statement that specifies primary input 
is discussed in the section "Data Set 
Reguirements. " 



SPECIFYING ADDITIONAL INPUT 



Additional input data sets are specified 
by the SYSLIB DD statement. The SYSLIB DD 
statement is discussed in the section "Data 
Set Reguirements." 

Note; Neither the overlay facility nor the 
segmentation feature can be used with the 
loader. 
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LIBRARIES 



Libraries are an integral part of the 
operating system. Some libraries have 
system-supplied names and system-supplied 
data. Other libraries have system-supplied 
names but may contain user-specified data. 
Still other libraries have both 
user-supplied names and user-supplied data. 



Libraries, in general, are made up of 
partitioned data sets. Any library with a 
user-supplied name and user-supplied data 
is always a single partitioned data set, 
which is a collection of independent sets 
of seguentially organized data, called 
members. All of the members within a 
partitioned data set have the same 
characteristics as that of record format. 
When used to store programs, a partitioned 
data set containing load modules can 
contain only load modules; it cannot 
contain both load modules and object 
modules. 



Each partitioned data set is headed by a 
directory of entries pointing to the 
members that make up the library. Each 
member has a unique member name. A 
partitioned data set must reside on a 
single mass storage device, but some 
libraries can consist of a concatenation of 
more than one partitioned data set. 



//DD1 DD DSNAME=FILELIB( FILED, X 

// DISP=(NEW, CATLG), X 

// UNIT=2311, X 

// SPACE=(TRK, (40,10,3)), X 

// VOLUME=SER=llllll 



This S*"a' , " c ' m S' r, t onopi -Fi oc f haf a 1 -i hrsru 

named FILELIB is to be created and 
cataloged in this job step. Its first 
member is named FILEl. Initial space 
allocated for data sets is to be 40 tracks, 
with additional allocation to be made, as 
necessary, in units of 10 tracks. In 
addition, space for three 256-byte records 
is to be allocated for the directory. The 
volume serial number is 111111. 

A member of a partitioned data set can 
be replaced or deleted. The system 
actually accomplishes this by modifying or 
deleting the directory pointer to the 
member. The space occupied by the original 
member is not available for reuse until the 
MOVE or COPY control statement of the 
IEHMOVE utility program is used. The space 
previously occupied by the replaced- or 
deleted member is thus made available. 
(For further details, see the publication 
IBM OS Utilities. ) 



Figure 91 shows the format of a library 
that is a single partitioned data set of 
four members. Space for the members of 
such a library and its directory is 
requested in the SPACE parameter of the DD 
statement when the library is created. 
Additional members can be added to a 
library at a later time. If additional 
space is required to store a member, 
allocation will be made in the amount 
specified by the secondary allocation in 
the SPACE parameter of the DD statement 
that was used when the library and its 
first member were created. Additional 
space cannot be allocated for the 
directory, however. Directory space is 
allocated for the entire library when the 
library is created. If the original 
allocation was not large enough, the 
IEHMOVE utility program can be used to 
expand the directory size. If the 
directory is filled, no additional members 
can be added to the library. Following is 
an example of a DD statement that might be 
used to create a library: 



KINDS OF LIBRARIES 



A programmer can use libraries already 
provided by the system, or he can create 
libraries of his own. In addition, certain 
library names recognized by the system may 
be assigned to partitioned data sets 
provided by the system, by the programmer, 
or both. These libraries and their uses 
are discussed in the following paragraphs. 



LIBRARIES PROVIDED BY THE SYSTEM 



Link L ibrary 



The link library is a partitioned data 
set that contains load modules to be 
executed. Unless specified otherwise, a 
load module name in an EXEC statement is to 
be fetched from the link library. 
Operating system programs, such as the 
COBOL compiler, are usually contained in 
this library. 
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Directory 



Library 
Members 



r T T T T 

Entry for | Entry for | Entry for | Entry for | 

Member A j Member B j Member C | Member K | Note 1 



Member C 



| Note 2 
-X 



Note 2 



| Member B | 



Member K 



Member K 



Member K 



Member A 



Member A 



Note 3 



Note 3 



N otes : 

1. Space available in directory. 

2. Space available from deleted member after data set has been 
compressed. 

3. Space available in library. 



Figure 91. Format of a Library 



The link library can be used by the 
programmer to store executable load modules 
at link-edit time. The technique for doing 
this is described in "Linkage Editor Data 
Set Requirements." 

The link library is identified in a job 
control statement as SYS1. LINKLIB. 



It is identified by the name 
SYS1.S0RTLIB (see "Using the Sort 
Feature" ) . 



COBOL Subroutine Library 



Procedure Library 



The procedure library is a partitioned 
data set whose members are the cataloged 
procedures at an installation. They 
include the cataloged procedures provided 
by IBM. Procedures written at the 
installation can be added to the procedure 
library with the IEBUPDTE utility program 
(see "Using the Cataloged Procedures"). 

The system name for the procedure 
library is SYSl. PROCLIB. 



Sort Library 



The sort library is a partitioned data 
set that contains load modules from which 
the sort program is produced. 



The COBOL subroutine library is a 
partitioned data set that contains the 
COBOL library subroutines in load module 
form. These subroutines may be included in 
a COBOL load module or dynamically loaded 
to perform such functions as data 
conversion and double precision aritnmetic. 
The COBOL programmer does not refer 
directly to these subroutines; calling 
sequences to them are generated at compile 
time from certain Procedure Division 
statements, and they are incorporated into 
the load module at link-edit time or loaded 
at program initialization time. A listing 
of subroutine names t functions, entry 
points, and size is given in Appendix B. 



The system name for the COBOL subroutine 
library is SYS1.C0BLIB. 
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LIBRARIES CREATED BY THE USER 



A programmer can create members of the 
link library, the procedure library, and 
the job library. He can also create 
partitioned data sets for use in the copy 
library, the automatic call library, and 
the job library. In addition, he can 
create partitioned data sets to be used as 
libraries for additional input to the 
linkage editor, and he can create libraries 
whose members are source program entries. 



Note; If the partitioned data set named in 
the SYSLIB DD statement contains load 
modules, any data set concatenated with it 
must also be a load module partitioned data 
set. If the first contains object modules, 
the others must also contain object 
modules. 

The linkage editor LIBRARY control 
statement has the effect of concatenating 
any specified member names with the 
automatic call library. 



Automatic Call Library 



COBOL Copy Library 



The automatic call library, defined by 
the SYSLIB DD statement in the link-edit 
job step, contains load modules or object 
modules that may be used as secondary input 
to the linkage editor. If the library 
contains object modules, it may also 
contain control statements. External 
symbols that are undefined after all 
primary input has been processed cause the 
automatic library call mechanism to search 
the automatic call library for modules that 
will resolve the references. The COBOL 
subroutine library must be specified for 
the automatic call library if any of the 
subroutines will be needed to resolve 
external references. Other partitioned 
data sets may be concatenated as shown in 
the following example: 

//SYSLIB DD DSNAME=SYSl.COBLIB,DISP=SHR 
// DD DSNAME=MYLIB, DISP=SHR 



In this case, both the COBOL subroutine 
library and the partitioned data set named 
MYLIB are available to the automatic 
library call. 



The COBOL copy library is a user-created 
library consisting of statements or entire 
COBOL programs frequently used by the 
programmer. The programmer can include 
these statements or programs into a program 
at compile time. He calls them with the 
COBOL COPY statement or BASIS card. 

To enter or update source statements in 
the copy library, a utility program must be 
used. IEBUPDTE is the IBM-supplied utility 
program used to catalog procedures. A full 
discussion of the statements used in this 
program may be found in the publication IBM 
OS Ut ilities. 

Entering Source Statements : Figure 92 
illustrates the method to insert source 
statements into a copy library member. 

The . / ADD statement is a utility 
statement that copies CFILEA into the 
library called COPYLIB. CFILEA describes 
an FD entry. The NUMBER statement assigns 
a sequential numbering system to the 
statements in the library. The first 
statement is assigned number 10 and each 



//CATALOG 


JOB 


// 


EXEC 


//SYSUT2 


DD 


// 




// 




// 




// 




//SYSPRINT 


DD 


//SYSIN 


DD 


./ 


ADD 


./ 


NUMB 



./ 
/* 



PGM=IEBUPDTE, PARM= (NEW) 
DSNAME=COPYLIB, UNIT=2311, 

DISP= (NEW, KEEP) , 

VOLUME=SER=llllll, 

SPACE=(TRK, (15,10,2) ) , 
DCB=(LRECL=8 0.BLKSIZE=80.RECFM=F) 
SYSOUT=A 
* 

NAME=CFILEA, LEVEL=00, SOURCE=0, LIST=ALL 
NUMBER NEW1=10,INCR=5 

BLOCK CONTAINS 13 RECORDS 

RECORD CONTAINS 120 CHARACTERS 

LABEL RECORDS ARE STANDARD 

DATA RECORD IS FILE -OUT. 
ENDUP 



Figure 92. Entering Source Statements into the COPY Library 
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I //UPDATE 
// 

//SYSUT1 
// 
// 
// 

//SYSUT2 
// 
// 

//SYSPRINT 
//SYSIN 
./ 

./ 
/* 



JOB 

EXEC PGM=IEBUPDTE, PARM= (MOD) 
DD DSNAME=COPYLIB,UNIT=2311, 
DISP= (OLD, KEEP), 
VOLUME=SER=llllll, 
DCB=(RECFM=F BLKSIZE=8 0) 
DSNAME=COPYLIB, UNIT=2311, 
DISP= (OLD, KEEP), 
VOLUME=SER=llllll 
SYSOUT=A 
* 

CHANGE NAME=CFILEA, LEVEL=01, SOURCE=0, LIST=ALL 

BLOCK CONTAINS 20 RECORDS 
ENDUP 



DD 



DD 
DD 



00000010 



Figure 93. Updating Source Statements in a COPY Library 



succeeding statement is incremented by 5. 
The entries following the utility 
statements are the actual source statements 
to be cataloged. The ENDUP statement 
signals the end of the entries to be 
inserted. 

The same procedure can be used to 
catalog entire source programs. 



COPY Statement 



The COPY statement permits the 
programmer to include cataloged source 
statements in the Data or Environment 
Divisions. If the programmer wishes to 
retrieve the member, CFILEA, cataloged in 
the previous examples, he writes the 
statement: 



Updating Source S tatem ents : Figure 93 
illustrates the method to update source 
statements in a copy library member 
inserted in the previous example. 

SYSUT1 and SYSUT2 describe the data 
sets. Note that changes may be made on the 
same data set (identified on the DSNAME 
parameter). The utility statement CHANGE 
indicates that the new entry of CFILEA 
replaces the old entry. The sequence 
number of the altered statement must be 
supplied. This number, 00000010, is 
indicated in columns 73 through 80 of the 
replacement source statement. Note that, 
although in the insert example (see Figure 
9 2 — NUMBER statement) the number was 
coded as 10 without leading zeros, the 
program assigns an 8-character field to a 
sequence number and pads with leading zeros 
if necessary. When updating a sequence 
number in a library, these leading zeros 
must be included. 

At compile time, COPYLIB is identified 
on a SYSLIB DD statement, as follows: 



//SYSLIB DD DSNAME=COPYLIB, 

// VOLUME=SER=llllll, 

// DISP=SHR, UNIT=2311 

Retrievi ng Source St a tements : Members of 
the cataloged library can be retrieved 
using the COPY statement or BASIS card. 



FD FILEA COPY CFILEA 



The compiler translates this instruction to 
read: 



FD FILEA BLOCK CONTAINS 20 RECORDS 
RECORD CONTAINS 120 CHARACTERS 
LABEL RECORDS ARE STANDARD 
DATA RECORD IS FILE-OUT. 



Note that CFILEA itself does not appear in 
the statement. CFILEA is a name 
identifying the entries. It acts as a 
header record but is not itself retrieved. 
The compiler source listing, however, will 
print out the COPY statement as the 
programmer wrote it. 



The COPY statement also permits the 
programmer to include previously cataloged 
source statements into the Procedure 
Division. 
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Assume a procedure named DOWORK was 
cataloged with the following statements: 

./ ADD NAME=DOWORK, LEVEL=00, 

SOURCE=0, LIST=ALL 
./ NUMBER SEQ1=400, INCR=10 
COMPUTE QTY-ON-HAND = 

TOTAL- USED-NUMBER-ON- HAND. 
MOVE-QTY- ON-HAND TO PRINT- ARE A. 
. / ENDUP 



To retrieve the cataloged member, DOWORK, 
the programmer writes: 

paragraph- name. COPY DOWORK. 



The statements included in the DOWORK 
procedure will immediately follow the 
paragraph-name, replacing the words COPY 
DOWORK. 



BASIS Card 



Frequently used source programs, such as 
a payroll program, can be inserted into the 
copy library. The BASIS card brings in an 
entire source program at compile time. 

Calling in. .a. .program .eliminat.es._the. need 

for the programmer to handle a program each 
time he wants to compile it. The 
programmer may, however, alter any 
statement in the source program by 
referring to its COBOL sequence number with 
an INSERT or DELETE statement. The INSERT 
statement will add new source statements 



after the sequence number indicated. The 
DELETE statement will eliminate the 
statements indicated by the sequence 
numbers. The programmer may delete a 
single statement with one sequence number, 
or he may delete more than one statement, 
separating by a hyphen the first and last 
sequence numbers to be deleted. 



Note : The COBOL sequence number is the 
6-digit number that the programmer assigns 
in columns 1 through 6 of the source cards. 
This sequence number has nothing to do with 
the sequence numbers assigned in simulated 
columns 73 through 80 by the IEBUPDTE 
utility program. The sequence numbers 
assigned by IEBUPDTE are used to update 
source statements in the copy library. 
Changes made using these numbers are 
intended to be permanent changes. The 
COBOL sequence numbers are used to update 
COBOL source statements at compile time. 
Such changes are in effect for the one run 
only. 

Assume that a company payroll program is 
kept as a source program in the copy 
library. The name of the program is 
PAYROLL. During a particular year, old age 
tax is taken out at a rate of two and a 
half percent each week for all personnel 
until, earnings exceed $6600. ._ ..The. coding... to. 
accomplish this is shown in Figure 94. 

Now, however, due to a change in the old 
age tax laws, tax is to be taken out until 
earnings exceed $7800 and a new percentage 
is to be placed. The programmer can code 
these changes as shown in Figure 95. 



COBOL 

Sequence 

Num bers 

000730 IF ANNUAL- PAY GREATER THAN 6600 GO TO PAY- WRITE. 

000735 IF ANNUAL-PAY GREATER THAN 6600 - BASE-PAY GO TO LAST-TAX. 

000740 TAX-PAYR. COMPUTE TAX-PAY = BASE-PAY * .025 



000750 



MOVE TAX-PAY TO OUTPUT-TAX. 



000760 PAY-WRITE. MOVE BASE-PAY TO OUTPUT-BASE. 



000770 



ADD BASE- PAY TO ANNUAL-PAY. 



000850 STOP RUN. 

Figure 94. COBOL Statements to Deduct Old Age Tax 



IEBUPDTE 
Sequence 
Numbers_ 
00000105 
00000110 
00000115 
00000120 
00000125 
00000130 



00000240 
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I BASIS PAYROLL 

| DELETE 000730-000740 

J000730 IF ANNUAL- PAY GREATER THAN 7800 GO TO PAY-WRITE. 

j 000735 IF ANNUAL-PAY GREATER THAN 7800 - BASE-PAY GO TO LAST-TAX. 

|000740 TAX-PAYR. COMPUTE TAX-PAY = BASE-PAY * .044. 

L 

Figure 95. Programmer Changes to Source Program 



000730 

000735 

000740 TAX-PAYR. 

000750 

000760 PAY-WRITE. 

000770 



IF ANNUAL-PAY GREATER THAN 7800 GO TO PAY-WRITE. 

IF ANNUAL-PAY GREATER THAN 7800 - BASE-PAY GO TO LAST-TAX. 

COMPUTE TAX-PAY = BASE-PAY * .044. 

MOVE TAX-PAY TO OUTPUT-TAX. 

MOVE BASE- PAY TO OUTPUT-BASE. 

ADD BASE- PAY TO ANNUAL- PAY. 



000850 STOP RUN. 

Figure 96. Changed COBOL Statements to Source COPY Library Statements 



The altered program will contain the 
coding shown in Figure 96. 



Note that changes made through use of 
the INSERT and DELETE statements remain in 
effect for the one run only. 

N ote : If both the COPY statement and the 
BASIS card are used, the library containing 
the member specified in the BASIS card must 
be defined first. The COPY libraries 
concatenated with the BASIS library may be 
defined and referenced in any order (see 
"Appendix I: Checklist for Job Control 
Procedures"). For a discussion of special 
considerations when using BASIS with the 
BATCH option, see "Batch Compilation." 



JOB Library 



The job library consists of one or more 
partitioned data sets that contain load 
modules to be executed. It is specified by 
the JOBLIB DD statement that must precede 
the EXEC statement of the first step of a 
job. Partitioned data sets assigned to the 
job library are concatenated with the link 
library so that any load module is obtained 
automatically when its name appears in the 
PGM= parameter of the EXEC statement. The 
following statements illustrate how three 



partitioned data sets can be assigned to 
the job library: 



//MYJOB 

//JOBLIB 

// 

// 

//STEP1 



//STEP2 



JOB . . . 

DD DSNAME=MYLIBl, DISP= (OLD, PASS) 
DD DSNAME=MYLIB2, DISP=(0LD, PASS) 
DD DSNAME=MYLIB3 J DISP= (OLD, PASS) 
EXEC 



EXEC . . . 



These statements specify that the job 
library containing the data sets MYLIB1, 
MYLIB2, and MYLIB3 is to be concatenated 
with the link library. When a load module 
is named in an EXEC statement in any step 
of the job, the directories of the job 
library will be searched for the name. 
When a job library is specified for a job, 
the link library is searched for a named 
load module only when the module is not 
found in the job library. 



Partitioned data sets used in the joo 
library can be created by specifying the 
partitioned data set name and the member 
name in the SYSLMOD DD statement when each 
member is processed by the linkage editor. 
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A ddi tional Input to the Linkage Editor; 
Libraries of object modules (with or 
without linkage editor control statements) 
and libraries of load modules can be used 
as additional input to the linkage editor. 
Members are specified by use of the INCLUDE 
and LIBRARY linkage editor control 
statements. 

A library of object modules and control 
statements can be created by use of the 
IEBUPDTE utility program. 

A library of load modules can be created 
by use of the SYSLMOD DD statement in the 
linkage editor job step, as discussed in 
"Job Library. " 



An installation that is planning to use 
the Library Management Feature will find it 
convenient to include frequently used COBOL. 
library subroutines in the MVT LPA or the 
MFT RRR area. Infrequently used 
subroutines are then brought into the 
region/partition as required. To add COBOL 
subroutines to either of these areas, the 
user invokes the IEBUPDTE utility program 
to add a member named IEAIGGXX (see Note 2 
in Figure 97) to SYS1. PARMLIB, specifying 
all names and aliases for the COBOL library 
subroutines to be included. Then, at an 
initial program load (IPL) time, the 
operator identifies the link list to the 
system, which subsequently places the 
identified COBOL subroutines in main 
storage in the LPA/RRR area. 



SHARING COBOL LIBRARY SUBROUTINES 



Use of the COBOL Library Management 
Feature makes it possible for all programs 
in the same or different regions/partitions 
to share one copy of the COBOL library 
subroutines. That is, the most economical 
use of main storage is made when the most 
frequently used COBOL library subroutines 
are placed in the MVT link pack area (LPA), 
or the MFT resident reusable routine (RRR) 
area r rather than in each -region/partition^ 
To make the most effective use of the 
Library Management Feature, and to use the 
IBM cataloged procedures whether or not 
Library Management is needed, the user 
should concatenate the COBOL subroutine 
library with the system link library. 

The user may request the COBOL Library 
Management Feature at compile time, via the 
RESIDENT option (see the section "Options 
for the Compiler" in the chapter entitled 
"Job Control Procedures"). 



CONCATENATING THE SUBROUTINE LIBRARY 



To concatenate the subroutine library 
with the link library, the user executes 
the IEBUPDTE utility program to add a 
member named LNKSTOO to SYS1. PARMLIB, 
specifying the library desired (that is f 
either the entire COBOL subroutine library 
or a private library containing 
user-selected COBOL library subroutines). 
Note that the library containing the 
subroutines must be cataloged. 



Figure 97 illustrates how an 
installation can accomplish both these 
functions in one operation. The encircled 
letters in the figure refer to the JCL 
suggested A to concatenate the COBOL 
subroutine library (SYS1. COBLIB) with the 
system link library (SYS1. LINKLIB) , and 
then B to place the user list of desired 
COBOL library subroutines and their aliases 
to the LPA/RRR. (For further information, 
see the publication OS Full Americ an 
Nat ional Standard COBOL Comp iler and 
Li-br-a ry T - -Ve r s ion- M- Ins ta 1 1 at ion - Ref e r en-c e 
Material. 



Notes : 

1. If the user does not wish to place any 
COBOL subroutines in the RRR/LPA area, 
he need not execute the portion of the 
IEBUPDTE utility program that adds 
IEAIGGXX to SYS1. PARMLIB shown above. 
He may still make use of the Library 
Management Feature. However, all 
required library subroutines will be 
loaded into his own region/partition 
when they are needed by one or more 
programs, and deleted when they are no 
longer needed. Thus, not all library 
subroutines needed by all programs in 
the region need be resident at the 
same time. In this case, however, the 
user must supply a job control card at 
execution time pointing to the COBOL 
subroutine library or to his own 
private library of COBOL subroutines. 
(For a discussion of the various COBOL 
library subroutines available to the 
programmer, see "Appendix B: COBOL 
Library Subroutines.") 
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//CATLG 


JOB 


// 


EXEC 


//SYSPRINT 


DD 


//SYSUT1 


DD 


//SYSUT2 


DD 


//SYSIN 


DD 


./ 


REPL 



./ 



ADD 



user information 

PGM=IEBUPDTE, PARM=MOD 

SYSOUT=A 

DSN=SYS1. PARMLIB, DISP=SHR 

DSN=SYSl. PARMLIB, DISP=SHR 

* 

NAME=LNKLST00, LIST-ALL 

SYS1. LINKLIB, SYSl. COBLIB 
NAME=IEAIGG01, LIST=ALL 

SYS1962(562B1,NAME1, ALIASl, 



/* 

Notes 



1. The name used in the JCL must identify the data set to oe concatenated with the 
system link library, and is selected by the installation. (Note that this data set 
must be cataloged. ) 

2. The last two digits of this member-name can vary, but the digits specified here 
must also be specified in the RAM= parameter used at IPL time. For example, if 
IEAIGG02 were specified, ' RAM=02' would be required at IPL time. 

3. The names and aliases of the COBOL library subroutine members to be made resident 
must be specified by the installation. The system searches the last name first; in 
this case, ALIAS1 is searched last. The user should, therefore, specify the most 
frequently used name last. 

L 

Figure 97. concatenating the Subroutine Library 



2. If one or more programs in a given 
region/partition request the COBOL 
Library Management Feature, then the 
main program and all subprograms in 
that region/partition must use it. 
Otherwise, the multiple copies of 
COBOL library subroutines resident at 
one time may cause unpredictable 
results. 



CREATING AND CHANGING LIBRARIES 



A programmer can create or change a 
partitioned data set in one of three ways: 

(1) through the use of DD statements, 

(2) through the use of utility programs, 
and (3) through the use of certain linkage 
editor control statements. 

The DD statement can be used to create 
libraries as is discussed at the beginning 
of this chapter. In addition, DD 
statements can be used to add members to 



existing libraries, including the link 
library, and to retrieve members of 
existing libraries. 



Utility programs can be used to create 
libraries such as those used in the copy 
library or as secondary input to the 
linkage editor. In addition, utility 
programs can be used to move, copy, and 
replace members of an existing library; to 
add, delete, and renumber the records 
within an existing library; and to assign 
sequence numbers to the records of a new 
library. 

Linkage editor control statements can be 
used to make changes to memoers of a 
library of load modules. The name of a 
member can be changed or additional names 
can be specified. Additional entry- points 
can be identified, existing entry points 
can be deleted, and portions of a load 
module can be deleted or replaced. For 
further information, see the publication 
IBM OS Linkage Edito r and Loader . 
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USING THE CATALOGED PROCEDURES 



A cataloged procedure is a set of job 
control statements placed in a partitioned 
data set called the procedure library 
rsYSl.PROCLIB) . It can be retrieved from 
the library by using its member name in an 
EXEC statement of a job step in the input 
stream. Frequently used procedures, such 

editing, can be cataloged to simplify their 
subsequent use. 

A cataloged procedure can contain 
statements for the processing of an entire 
job, or it can contain statements to 
process one or more steps of a job, with 
the remaining steps defined by job control 
statements in the input stream. A job can 
use several cataloged procedures, each 
processing one or more of the job steps. A 
job can also call for execution of the same 
cataloged procedure in more than one job 
step. 

This chapter describes the following: 

• How to call cataloged procedures 



The types of cataloged procedures, 
including those supplied by IBM for use 
with COBOL source programs 



procedure COBUC to process the job step 
STEPQ. 

A job step that calls for execution of i 
cataloged procedure can also contain DD 
statements that are applicable to the job 
steps of the cataloged procedure. A job 
that calls for execution of a cataloged 
procedure may, in other steps, call for 
execution of other cataloged procedures, 
call for other executions of the same 
cataloged procedure, or call directly for 
execution of load modules. The following 
example shows a job control procedure that 
calls both cataloged procedures and load 
modules. 



//J0B1 


JOB 




//STEPA 


EXEC 


COBUC 


//COB.SYSIN 


DD 


* 



(source module) 



/* 

//STEPL 



EXEC 



PGM=IEWL 



(DD statements for the linkage editor) 



• How to add procedures to the procedure 
library 



• How to modify existing procedures for 
the current job step only 



//STEPE 



EXEC 



PGM=*. STEPL. SYSLMOD 



• How to override and add to cataloged 
procedures 

• How to use the DDNAME parameter in 
cataloged procedures 



(DD statements for user-defined files) 



CALLING CATALOGED PROCEDURES 



A cataloged procedure is called by a job 



.1,-1. ., 



appears i 



11 1,11c 



mpUo s i.rear 



must consist of a JOB statement and an EXEC 
statement that specifies the cataloged 
procedure name in the positional parameter 
(either procname or PROC=procname) . For 
example: 

//STEPQ EXEC COBUC 
//STEPQ EXEC PROC=COBUC 



Either of these EXEC statements could be 
used to call the IBM-supplied cataloged 



The IBM-supplied cataloged procedure 
COBUC for compilation is used to process 
STEPA. The COB. SYSIN DD statement is 
ZQQXX\£Q& to define the input to the 
compiler. The remaining statements in the 
procedure refer to execution of the linkage 
editor and the subsequent load module. 



Data S ets Produced by Cataloged Procedu res 



Data sets produced during execution of a 
cataloged procedure can be used in 
subsequent job steps. They can also be 
called as follows: 
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//jobname JOB 1234, J.SMITH 
//STEPA EXEC PROCED 
//PROCl.SYSIN DD * 

(source module) 

/* 

//stepname EXEC PGM=*. STEPA. PROC2.SYSLMOD 



(DD statements for user-defined files) 



The cataloged procedure PROCED is 
composed of two job steps, PROC1 and PR0C2, 
that compile and linkage edit the source 
module. 



TYPES OF CATALOGED PROCEDURES 



1. The JOB statement 

2. A DD statement with JOBLIB in the 
name field 

3. A DD statement with an * in the 
operand field 

4. A DD statement with DATA in the 
operand field 

5. The delimiter statement 



Testing Programmer-Written Procedures 



A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stream procedure 
and executing it any number of times durinq 
a job. For further information about 
in-stream procedures, refer to the section 
"Testing a Procedure as an In-Stream 
Procedure". 



The programmer can write his own 
procedures and catalog them, or he can use 
the five COBOL cataloged procedures 
provided by IBM. 



PROGRAMMER- WRITTEN CATALOGED PROCEDURES 



The programmer can write cataloged 
procedures, consisting of EXEC and DD 
statements, which incorporate job control 
procedures he uses frequently. For 
example, the programmer may wish to catalog 
an EXEC statement and the associated DD 
statements for a job step that specifies 
execution of a program. In this way, the 
DD statements need not be specified each 
time the program is executed. 

In writing a procedure for cataloging, 
the programmer must follow these rules: 

• Another cataloged procedure cannot be 
referred to, i.e., only the 
PGM=progname form in an EXEC statement 
can be used. 

Note, however, that a cataloged 
procedure may contain a DD statement 
that refers to a cataloged data set. 

• SYSABEND or SYSUDUMP DD statements 
should not be cataloged because they 
cannot be overridden. 

• The following statements cannot be used 
in a cataloged procedure: 



Addin g Pro cedure s to the Procedure Library 



The IEBUPDTE utility program is used to 
add procedures to the procedure library. A 
description of the use of this program is 
given in the publication IBM OS Ut ilities. 

In Figure 98, two procedures are added 
to the procedure library (SYSl. PROCLIB) . 
All control statements are in the input 
stream. 

The first procedure is for a COBOL 
compilation. Mass storage volumes are 
specified for the four utility data sets, 
and 100 tracks are allocated for each 
utility data set. This cataloged procedure 
is named COBDA. 

The second procedure is also for a COBOL 
compilation. Unlaoeled tape volumes are 
specified for three utility data sets; for 
the fourth, SYSUTl, a mass storage device 
must be specified. This cataloged 
procedure is named COBTP. 

Job control statements: the EXEC card 
specifies that the IEBUPDTE program is to 
be executed, and PARM=NEW is used because 
all data is read from one source, i.e., the 
input stream. 

Utility statements: the ADD statement 
specifies the member name of the procedure, 
the level modification (00, first run) and 
the source of the modification (0, 
user-supplied). The NUMBER statement 
specifies the sequence numbers for records 
in the member. The first record of the 
cataloged procedure is numbered 00000010, 
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and subsequent records are incremented by 
tens. 



Note that leading zeros in the NUMBER 
statement are not necessary, as indicated 
in the example for the COBTP procedure. 



ItSM-tSUi'Flj.LlSU UATAliUliEU FKUCfcDUKiSS 



IBM distributes cataloged procedures 
with the operating system, which can be 
incorporated when the system is generated. 



Five of the procedures are for use with 
COBOL programs. 

1. COBUC provides for compilation. 

2. COBUCL provides compilation and 
linkage editing. 

3. COBULG provides linkage editing and 
execution. 



4. COBUCLG provides for compilation, 
linkage editing, and execution. 

5. COBUCG provides for compilation and 
loading. 



These procedures may be used with any of 
the job schedulers released as part of the 
IBM Operating System. When parameters 
required by a particular scheduler are 
encountered by another scheduler that does 
not require those parameters, either they 
are ignored or alternative parameters are 
substituted automatically. 



The five cataloged procedures are shown 
in Figures 99, 100, 101, 102, and 103. 
(Space allocations in these procedures are 
in terms of record lengths on the 2311 disk 
storage device.) Note that when DSNAME=SS 
is used in a DD statement the specified 
data set is given a unique name by the 
operating system, and it is assumed to be a 
temporary data set that will be deleted 
when the job is completed. If the data set 
is to be kept, the DD statement can be 
overridden with a permanent data set name, 
and the appropriate parameters can be 
specified. 



| Job 


//ADPROC 


JOB 


j Control 


//STEP1 


EXEC 


| Language 


//SYSPRINT 


DD 


j Statements 


//SYSUT2 


DD 




//SYSIN 


DD 


| Utility 


./ 


ADD 


j Statements 


./ 


NUMBER 




//COB 


EXEC 




//SYSUT1 


DD 




//SYSUT2 


DD 


| First 


//SYSUT3 


DD 


j Procedure 


//SYSUT4 


DD 




//SYSPRINT 


DD 




//SYSPUNCH 


DD 


| Utility 


./ 


ADD 


j Statements 


./ 


NUMBER 




//COB 


EXEC 




//SYSUT1 


DD 


| Second 


//SYSUT2 


DD 


j Procedure 


//SYSUT3 


DD 




//SYSUT4 


DD 




//SYSPRINT 


DD 




//SYSPUNCH 


DD 


j Delimiter 


./ 


ENDUP 


| Statements 
i 


/* 




Figure 98. 


Example of Adding Pr< 



1234, J. DUBOB 

PGM=IEBUPDTE, PARM=NEW 

SYSOUT=A 

DSNAME=SYS1. PROCLIB, DISP=OLD 

DATA. 

NAME=COBDA, LEVEL=00, SOURCE=0 
NEW1=00000010, INCR=00000010 

PGM=IKFCBL00 

UNIT=SYSDA, SPACE= ( TRK, (100,10)) 

UNIT=SYSDA, SPACE=(TRK, (100,10)) 

UNIT=SYSDA, SPACE=(TRK, (100,10)) 

UNIT=SYSDA, SPACE=(TRK, (100,10)) 

SYSOUT=A 

SYSOUT=B 

NAME=COBTP, LEVEL=00, SOURCE=0 
NEW1=10,INCR=10 

PGM=IKFCBL00 

UNIT=SYSD A, SPACE= ( TRK, (100,10)) 

UNIT= 2 4 , LABEL= ( , NL ) 

UNIT=24 00,LABEL=(,NL) 

UNIT=2400 , LABEL= ( , NL) 

SYSOUT=A 

SYSOUT=B 
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Note: If the compiler options are not 
explicitly supplied with the procedure, 
default options established at the 
installation apply. The programmer can 
override these default options by using an 
EXEC statement that includes the desired 

«-\ri+- -i nn o (cqq "nuQrr-idi nn ztnri h.rtr\-i r\rt ¥ r> 'P'Y'Pr' 

Statements" and "Overriding Cataloged 
Procedures Using Symbolic Parameters"). 



to the SYSSQ name. Then again, both 2400 
Magnetic Tape Units and 2311 Disk Storage 
Drives might be assigned to the SYSSQ name 
Once a pool of devices is assigned to these 
classes, device selection is done by the 
Job Scheduler. 



Data Set Names in Procedures 



Procedure Naming Conventions 



Procedure names begin with the 
abbreviated name of the processor program, 
which, in the case of the COBOL procedures, 
is COB. 



The processor's abbreviated name is 
followed by the processor's level indicator 
(U) and then by C (compile), L (linkage 
edit), G (go — i.e., execute), or 
combinations of them. Hence, procedure 
COBUC is a single-step procedure that 
compiles a program using the COBOL 
processor; COBUCLG is a 3-step procedure 
wherein the first step compiles a program 
using COBOL, the second step link-edits the 
output of the first step, and the third 
step executes the output of the linkage 
editor. 



S tep Names in Pr ocedures 



In a cataloged procedure, the step name 
is the same as the abbreviated processor 
name (LKED). The step that executes a 
compiled and link-edited program is named 
GO. 



When DSNA.ME=&&name is used in a DD 
statement, the specified data set is given 
a unique name by the scheduler, and it is 
assumed to be a temporary data set that 
will be deleted when the job terminates. 
If the data set is to be retained, the DD 
statement must be overridden with a 
permanent data set name and appropriate 
DISP parameters. 



COBUC Procedure 



The COBUC procedure is a single-step 
procedure to execute the COBOL compiler. 
It produces a punched object deck. Figure 
99 shows the statements that make up the 
COBUC cataloged procedure. 

The following DD statement must be 
supplied in the input stream: 



//C0B.SYS1N DD * 



(or appropriate 
parameters defining an 
input data set) 



If the DD * statement is used under MFT, 
the delimiter statement (/*) must follow 
the source module. Under MVT, the /* 
statement is not required. 



For example, in the procedure named 
COBUCLG, the first step is named COB, the 
second step is named LKED, and the third 
step is named GO. 



Unit Names in Procedures 



The two unit names used in IBM-supplied 
cataloged procedures are as follows: 

SYSSQ any magnetic tape or mass 
storage device 

SYSDA. any mass storage device 

A pool of units must be assigned to 
these unit names during the system 
generation procedure. For example, only 
2311 Disk storage Drives might be assigned 



COBUCL Procedure 



The COBUCL procedure is a two-step 
procedure to compile and link-edit using 
the COBOL compiler. Figure 100 shows the 
statements that make up the cataloged 
procedure. 

The COB job step produces an object 
module that is input to the linkage editor. 
Other object modules may be added as 
illustrated in Example 5 under "Using the 
DDNAME Parameter. " 

The following DD statement, indicating 
the location of the source module, must be 
supplied in the input stream: 



//COB.SYSIN DD * 



(or appropriate 
parameters) 
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COBULG Procedure 



The COBULG cataloged procedure is a 
two-step procedure to link-edit and execute 
the output of a COBOL compilation. Figure 
101 shows the statements that make up the 
procedure. 

The following DD statement indicating 
the location of the object module must be 
supplied in the input stream: 



//LKED.SYSIN DD * 



(or appropriate 
parameters) 



If the COBOL program refers to SYSIN in 
the execution step, the following DD 
statement must also be supplied and must be 
the last of the //GO, cards. 



//GO.SYSIN DD * 



(or appropriate 
parameters) 



If the COBOL program refers to other 
data sets in the execution step such as 
user-defined files, DD statements that 
define these data sets must also be 



| //COB 
I //SYSPRINT 
I //SYSPUNCH 
| //SYSUTl 
| //SYSUT2 
j //SYSUT3 
j //SYSUT4 
L 

Figure 99. 



EXEC PGM=IKFCBL00, PARM=' DECK, NOLOM), SUPMAP' , REGION=86K 

DD SYSOUT=A 

DD SYSOUT=B 

DD DSNAME=S6SYSUTl l UNIT=SYSDA, SPACE=(460, (700,100)) 

DD DSNAME=&SSYSUT2,UNIT=SYSDA,SPACE=(4 60, (700,100)) 

DD DSNAME=&&SYSUT3,UNIT=SYSDA,SPACE=(460, (700,100)) 

DD DSNAME=6&SYSUT4,UNIT=SYSDA,SPACE=(4 60, (700,100)) 



Statements in the COBUC Procedure 



| //COB EXEC PGM=IKFCBL00,REGION=86K 

| //SYSPRINT DD SYSOUT=A 

J//SYSUT1 DD DSNAME=SSSYSUT1, UNIT=SYSDA, SPACE= ( 460, (700,100) ) 

J//SYSUT2 DD DSNAME=&SSYSUT2,UNIT=SYSDA f SPACE=( 460, (700,100) ) 

J//SYSUT3 DD DSNAME=&SSYSUT3 # UNIT=SYSDA,SPACE=( 460, (700,100) ) 

|//SYSUT4 DD DSNAME=&SSYSUT4,UNIT=SYSDA,SPACE=(460, (700,100) ) 

J//SYSLIN DD DSNAME=S&LOADSET,DISP= (MOD, PASS), UNIT=SYSDA I X 

|// SPACE=(80, (500,100)) 

I//LKED EXEC PGM=IEWL, PARM=' LIST, XREF, LET' ,COND=(5,LT, COB) , X 

|// REGION=96K 

|//SYSLIN DD DSNAME=&SLOADSET,DISP= (OLD, DELETE) 

|// DD DDNAME=SYSIN 

J//SYSLMOD DD DSNAME=66GOSET,DISP= (NEW, PASS) ,UNIT=SYSDA, X 

|// SPACE=(1024, (50,20,1)) 

J//SYSLIB DD DSNAME=SYSl.COBLIB,DISP=SHR 

|//SYSUT1 DD UNIT=(SYSDA,SEP=(SYSLIN,SYSLMOD)) , X 

|// SPACE=(1024, (50,20)) 

j //SYSPRINT DD SYSOUT=A 

L 

Figure 100. Statements in the COBUCL Procedure 



Using the Cataloged Procedures 29 3 



I //LKED 
| //SYSLIN 
| //SYSLMOD 

I// 

|//SYSLIB 

J//SYSUT1 

!// 

J//SYSPRINT 

| //GO 

L 

Figure 101. 



EXEC PGM=IEWL, PARM=' LIST, XREF, LET' , REGION=96K 

DD DDNAME=SYSIN 

DD DSNAME=6&GOSET(GO) , DISP= (NEW, PASS) , UNIT=SYSDA, 

SPACE=(1024, (50,20,1) ) 
DD DSNAME=SYSl.COBLIB,DISP=SHR 
DD DSNAME=S SSYSUT1 , UNIT= ( S YSDA, SEP= ( S YSLIN, SYSLMOD ) ) , 

SPACE= (1024, (50, 20) ) 
DD SYSOUT=A 
EXEC PGM= * . LKED. SYSLMOD, COND= ( 5 , LT , LKED ) 



Statements in the COBULG Procedure 



| //COB EXEC PGM=IKFCBL00 f PARM=SUPMAP, REGION=86K 

J//SYSPRINT DD SYSOUT=A 

J//SYSUT1 DD DSNAME=&SSYSUT1,UNIT=SYSDA,SPACE=(460, (700,100) ) 

J//SYSUT2 DD DSNAME=S&SYSUT2,UNIT=SYSDA,SPACE=(460, (700,100) > 

|//SYSUT3 DD DSNAME=&&SYSUT3, UNIT=SYSDA,SPACE= (460, (700,100) ) 

|//SYSUT4 DD DSNAME=&SSYSUT4,UNIT=SYSDA, SPACE=( 460, (700,100) ) 

| //SYSLIN DD DSNAME=S &LOADSET, DISP= ( MOD, PASS), UNIT=SYSDA, X 

|// SPACE=(80, (500,100) ) 

J//LKED EXEC PGM=IEWL, PARM=' LIST, XREF, LET* , COND= ( 5, LT, COB) , X 

|// REGION=96K 

J//SYSLIN DD DSNAME=£&LOADSET,DISP=( OLD, DELETE) 

|// DD DDNAME=SYSIN 

J//SYSLMOD DD DSNAME=&&GOSET (GO) , DISP= < NEW, PASS) , UNIT=SYSDA, X 

|// SPACE=(1024, (50,20,1)) 

|//SYSLIB DD DSNAME=SYSl.COBLIB,DISP=SHR 

|//SYSUT1 DD UNIT=(SYSDA,SEP=( SYSLIN, SYSLMOD)), X 

|// SPACE=(1024, (50,20)) 

|//SYSPRINT DD SYSOUT=A 

| //GO EXEC PGM=*.LKED. SYSLMOD, COND=( (5, LT, COB) , (5, LT, LKED)) 



Figure 102. Statements in the COBUCLG Procedure 



//COB EXEC PGM=IKFCBL00,PARM='LOAD» ,REGION=86K 

//SYSPRINT DD SYSOUT=A 

//SYSUT1 DD DSNAME=&&SYSUT1,UNIT=SYSDA,SPACE=(460, (700,100) ) 

//SYSUT2 DD DSNAME=&6SYSUT2,UNIT=SYSDA, SPACE=(460, (700,100) ) 

//SYSUT3 DD DSNAME=&£SYSUT3,UNIT=SYSDA, SPACE=( 460, (700,100) ) 

//SYSUT4 DD DSNAME=&SSYSUT4,UNIT=SYSDA, SPACE=(460, (700, 100) ) 

//SYSLIN DD DSNAME=&&LOADSET, DISP= (MOD, PASS) , 

// UNIT=SYSDA, SPACE=(80, (500,100)) 

//GO EXEC PGM= LOADER, PARM=' MAP, LET', COND=( 5, LT, COB) ,REGION=106K 

//SYSLIN DD DSNAME=*.COB. SYSLIN, DISP=< OLD, DELETE) 

//SYSLOUT DD SYSOUT=A 

//SYSLIB DD DSNAME=SYSl.COBLIB,DISP=SHR 



Figure 103. Statements in the COBUCG Procedure 
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COBUCLG Procedure 



The COBUCLG procedure is a three-step 
procedure to compile, link-edit, and 
execute using the COBOL compiler. Figure 
102 shows the statements that make up the 
procedure. 



The COB job step produces an object 
module that is input to the linkage editor. 
Other object modules may be added as 
illustrated in Example 5 under "Using the 
DDNAME Parameter. " 



If the COBOL program refers to other 
data sets, the DD statements that define 
these data sets must also be supplied. 



MODIFYING EXISTING CATALOGED PROCEDURES 



Existing cataloged procedures can be 
permanently modified by using the IEBUPDTE 
utility program described in the 
publication IBM OS Utilitie s. 



The following DD statement, indicating 
the location of the source module, must be 
supplied in the input stream: 



//COB.SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to SYSIN, 
the following DD statement indicating the 
location of the input data set must also be 
supplied: 



//GO. SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to other 
data sets, DD statements that define these 
data sets must also be supplied. 



COBUCG Procedure 



The COBUCG procedure is a two-step 
procedure to compile, load, and execute 
using the COBOL compiler and OS loader. 
Figure 103 shows the statements that make 
up the procedure. 

The COB job step produces an object 
module that is input to the loader. 

The following DD statement, indicating 
the location of the source module, must be 
supplied in the input stream: 



//COB.SYSIN DD 



* (or appropriate 
parameters) 



If the COBOL program refers to SYSIN, 
the following DD statement indicating the 
location of the input data set must also be 
supplied: 



OVERR IDING AND ADDING TO CATALOGED 
PROCEDURES 



Any_ parameter in a_ cataloged procedure 
except th_e~Z^fe in, the 

'ElCE^lstatemejit^.pan be overridden. 
Parameters or statements not specified in 
the procedure can also be added. When a 
cataloged procedure is overridden or added 
to, the changes apply only during one 
execution. 



OVERRIDING AND ADDING TO EXEC STATEMENTS 



//GO. SYSIN DD 



* (or appropriate 
parameters) 



An EXEC statement can be overridden or 
added to in one of two ways : 

1. Specify, in the operand field of the 
EXEC statement calling the procedure, 
the keyword, the procedure step-name 
and the subpararneters, for example: 

COND. procstep= ( subpararneters ) 

If a multistep procedure is being 
modified, parameters in the calling 
EXEC statement must be specified step 
by step; i.e., the parameters for one 
step must be specified before those of 
the next step. If the return code of 
a cataloged procedure step is to be 
tested, the name of the step in the 
procedure (procstep) must be qualified 
by the name of the step that called 
for execution of the cataloged 
procedure (stepname). 

2. Specify in the operand field of the 
EXEC statement calling the procedure 
only the keyword parameters and 
subpararneters, for example: 

COND= ( subpararneters ) 

If a multistep procedure is being 
called, the specified parameters (with 
the exception of PARM) apply to ail 
steps in the procedure. The PARM 
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keyword subparameters override the //jobname 

first EXEC statement and nullify any //STEPA 

subsequent PARM keyword subparameters. // 

The COND and ACCT parameters apply to // 

all steps in the procedure. To // 

override PARM parameters in job steps //COB. SYSIN 
other than the first, the previous 
method can be used. 



JOB 1234, J. SMITH 
EXEC COBUCLG, COND. LKED= 
( 9, LT, STEPA. COB), 
PARM. LKED= (MAP, LIST) , 
ACCT=<1234) 
DD * 

(source module) 



Note : A parameter in an EXEC statement 
cannot be partly overridden; it must be 
overridden in its entirety. Any parameter 
not overridden remains as originally 
defined. 



/* 



Note : In actual use the COND. LKED and 
PARM. LKED parameters cannot be continued in 
this manner. For the linkage editor job 
step in the above example, the COND and 
PARM parameters have been overridden and 
the ACCT parameter added. 



Examples of Overriding and Adding to EXEC 
Statements 



This section contains examples of 
overriding and adding to the EXEC 
statement. The procedures overridden or 
added to are the IBM procedures shown in 
Figures 99, 100, 101, 102 and 103. 



Exam p le 1 : The following example shows the 
overriding of one parameter in the EXEC 
statement of the one procedure step in the 
IBM-supplied COBUC procedure. The 
statements appear in the input stream as 
follows: 



//jobname 

//STEPA 

// 

// 



JOB 1234, J. SMITH 

EXEC COBUC, PARM. COB=' DECK, 

NOLOAD,BUF=4000, 

SIZE=9600» 



//COB. SYSIN DD 



(source module) 



/* 



Example 3 : The following example shows the 
overriding of individual parameters in more 
than one procedure step of the IBM-supplied 
COBUCLG procedure. The statements appear 
in the input stream as shown. 

//jobname JOB 1234, J. SMITH 

//Stepname EXEC COBUCLG, PARM. LKED=OVLY, X 
// COND. GO=( (5,EQ, X 

// stepname. COB) , X 

// (5, EQ, stepname. LKED) ) 

//COB. SYSIN DD * 

(source module) 



/* 



Note: In actual use the COND. GO statement 
cannot be continued in this manner. The 
PARM option OVLY replaces the PARM 
subparameters of the link-edit job step. 
The COND option EQ (equal to) replaces the 
option LT (less than) in the execution job 
step. 

Note that all overriding parameters for 
one step of the procedure must be specified 
before those for the next step. 



Note : In actual use the PARM. COB parameter 
cannot be continued in this manner. In the 
PARM parameter that is overridden, the DECK 
and NOLOAD options were specified. They 
are included again since the parameter must 
be overridden in its entirety. The 
information is here enclosed in single 
quotation marks, since subparameters that 
contain equal signs must be enclosed in 
this manner. 



Example 2 : The following example shows the 
overriding of two parameters and the adding 
of another in the EXEC statement of one 
procedure step of the IBM-supplied COBUCLG 
procedure. The statements appear in the 
input stream as shown: 



Example 4 : The following example shows the 
overriding of parameters on all EXEC 
statements in the IBM-supplied COBUCLG 
procedure. The statements appear in the 
input stream as shown: 



//jobname JOB 

//stepname EXEC 

// 

// 

// 

//COB. SYSIN DD 



1234, J. SMITH 

COBUCLG, X 

PARM=(LOAD,PMAP), X 
COND= ( 3 , LT ) , X 

ACCT=(123456, DEPTQ) 



(source module) 



/* 
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The PARM options are added to the procedure 
step COB and nullify the PARM options in 
the LKED and GO steps. The COND and ACCT 
parameters apply to all steps in the 
procedure. 



TESTING A PROCEDURE AS AN IN-STREAM 
PROCEDURE 



OVERRIDING AND ADDING TO DD STATEMENTS 



A DD statement can be overridden or 
added to by using a DD statement whose name 
is composed of the procedure step-name that 
qualifies the ddname of the DD statement 
being overridden, as follows: 

//procstep. ddname DD (appropriate 

parameters) 



Entire DD statements can also be added. 



A procedure can be tested before it is 
placed in the procedure library by 
converting it into an in-stream procedure 
and executing it any number of times during 
a job. In-stream procedures are described 
in detail in the publication I BM OS Job 
Cont rol Language R eference . 



An in-stream procedure is a series of 
job control language statements enclosed 
within a PROC statement and a PEND 
statement. The following example shows how 
to convert the COBUC procedure (Figure 99) 
into an in-stream procedure and execute it 
twice: 



//CONVERT 


JOB 


//INSTREAM 


PROC 


//COB 


EXEC 


//SYSPRINT 


DD 


//SYSPUNCH 


DD 


//SYSUTl 


DD 



//SYSUT2 



//SYSUT3 



//SYSUT4 



//ENDPROC 

// 

//COB. SYSIN 



DD 



DD 



DD 



PEND 
EXEC 
DD 



1234, YOURNAME 

PGM=IKFCBL00,PARM=' DECK, X 

NOLOAD, SUPMAP' ,REGION=86K 

SYSOUT=A 

SYSOUT=B 

DSNAME=SS SYSUTl, 

UNIT=SYSDA, 

SPACE=(460, (700,100)) 

DSNAME=6&SYSUT2, 

UNIT=SYSDA, 

SPACE=(460, (700,100) ) 

DSNAME=&SSYSUT3 f 

UNIT=SYSDA, 

SPACE=(460, (700,100)) 

DSNAME=&&SYSUT4, 

UNIT=SYSDA, 

SPACE=(460, (700,100) ) 

INSTREAM 

* 



(input data) 

/* 

// EXEC INSTREAM 

//COB. SYSIN DD * 



(input data) 



/* 



There are rules that must be followed 
when overriding or adding a DD statement 
within a step in a procedure. 

• Oj^ejrridirig_ pp_ statements must be _ in the 
same order in jthefinput .stream as they 
are "Xn the cataloged procedure" 

• DD stajtejuejits^^ ^ follow 
"overriding DD statements. '""""* 

• J^^J^Si§JBe Jit with an * i n tne operand 

f i e 1 d_ t e r mi naj:jss_ j^r 6c e "s "si "ng^SF"~"~' '""""' """ 

sTubs^equent DD statements Tri both the 
procedure,., and the input StTeam "for" the 
~jc»b step, out not necessarily for the 
jrrby; ■■ "7.^._.'„ ' "."'.. '.' '". ".'.''"' 



There are some special cases that snould 
be kept in mind when overriding a DD 
statement. 

• All parameters are overridden in their 
entirety, except for the DCB parameter. 
Within the DCB parameter, individual 
subparameters may be overridden. 

• To nullify a keyword parameter (except 
the DCB parameter), write, in the 
overriding DD statement, the keyword 
and an equal sign followed by a comma. 
For example, to nullify the use of the 
UNIT parameter, specify UNIT=, in the 
overriding DD statement. 

• A parameter can be nullified by 
specifying a mutually exclusive 
parameter. For example, the SPACE 
parameter can be nullified by 
specifying the SPLIT parameter in the 
overriding DD statement. 

• The DUMMY parameter can be nullified by 
omitting it and specifying the DSNAML 
parameter in the overriding DD 
statement. 

• To override DD statements in a 
concatenation of data sets, the 
programmer must provide one DD 
statement for each data set in the 
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concatenation. Only the first DD 
statement in the concatenation should 
be named. However, if a DD statement 
to be changed follows one (or more) DD 
statement(s) to be left intact, the 
first overriding statement (s) should 
have a blank operand. 



If the DDNAME=ddname parameter is 
specified in a cataloged procedure, it 
cannot be overridden; rather it can 
refer to a DD statement supplied at the 
time of execution. 



Example 2 ; The following example shows the 
adding of DD statements to the IBM-supplied 
COBUCLG procedure. Note that if the 
statement DD * or the statement DD DATA is 
used, it must be the last to appear in a 
series of DD statements. 

//jobname JOB 1234, J. SMITH 
//stepname EXEC COBUCLG, X 

// PARM. COB= ( DECK, LOAD, PVLAP ) 

//COB.SYSPUNCH DD SYSOUT=B 
//COB. SYSIN DD * 

(source module) 



Examples of Overriding and Adding to DD 
Statements 



/* 

//GO. TRANSACT 



DD DSNAME=JUNE ( DISP=OLD 



This section contains examples of 
overriding and adding to parameters in DD 
statements. The procedures overridden or 
added to are the IBM procedures shown in 
Figures 99, 100, 101, 102 and 103. 

The DDNAME parameter is not used in 
these examples, although it can be useful 
with the cataloged procedures. The use of 
the DDNAME parameter is described in detail 
later in this chapter. 



Example 1 : The following example shows the 
overriding of DD statements in the 
IBM-supplied COBUCLG procedure. 



(other DD statements for 
user-defined files) 



/* 



Note : In the foregoing example TRANSACT is 
a cataloged data set. When a data set is 
cataloged, it is sufficient to refer to it 
by DSNAME and DISP=OLD. 

The PARM. COB option DECK and the SYSPUNCH 
DD statement are added to obtain a punched 
object module. The PARM option PMAP is 
added to obtain a listing of the assembler 
language expansion of the source module. 



//jobname 
//stepname 
//COB. SYSLIN 
//COB. SYSIN 



JOB 1234, J. SMITH 
EXEC COBUCLG 
DD DSNAME=GOFILE 
DD * 



(source module) 



/* 

//LKED. SYSLIN 

// 



DD DSNAME=*. COB. SYSLIN, 
DISP=(OLD,CATLG) 



/* 



(other DD statements for 
user-defined files) 



Examp_le_3: The following example shows 
overriding and adding to DD statements at 
the same time in the IBM-supplied COBUC 
procedure. Note that overriding statements 
must be in the same sequence as they appear 
in the procedure and must precede those 
statements being added. 



//jobname 

//stepname 

//COB.SYSUT2 

//COB. SYSLIN 

// 

// 

//COB. SYSIN 



JOB 1234, J. SMITH 

EXEC COBUC , PARM. COB= ( LOAD ) 

DD SPACE=, UNIT=SYSSQ 

DD DSNAME=SSGOFILE, X 

DISP= (MOD, PASS) , X 

UNIT=SYSSQ 
DD * 



(source module) 



/* 



/* 



The name of the data set in SYSLIN in the 
procedure step COB is changed to GOFILE. 
The name of the data set of SYSLIN in the 
procedure step LKED is changed to a 
reference to the SYSLIN DD statement in the 
COB procedure step, and the data set name 
GOFILE is cataloged. 



(subsequent job steps) 



The device class on the COB. SYSUT2 DD 
statement is changed to SYSSQ, and the 
SPACE parameter is nullified. Therefore, 
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mass storage devices cannot be allocated. 
Any tape volumes to be assigned must have 
standard labels. The COB.SYSLIN DD 
statement is changed so that it passes the 
object module to subsequent job steps. 



Example 4 : The following example shows how 
to concatenate a data set with a data set 
defined in the COBULG procedure. 



//jobname JOB 
//stepname EXEC 



//LKED. SYSLIB DD 
// DD 



1234, J. SMITH 
COBULG 



[blank operand field] 
[parameters] 



DDNAME parameter cannot be used because 
the statement that is referred to loses 
its identity. 



• A backward reference to a statement 
containing a DDNAME parameter can be 
used, but only after the statement to 
which the DDNAME parameter refers has 
been encountered. If a backward 
reference is used before the dummy data 
set (defined by DDNAME) has been given 
real characteristics, these real char- 
acteristics will not be transferred to 
the DD statement that contains the 
backward reference. For example, if 
DCB=*.ddname is used (where ddname is 
the name of a statement containing an 
unresolved DDNAME parameter), the DCB 
fields that are transferred are blank. 



/* 



Instead of the blank operand field, 
parameters could have been used to override 
the SYSLIB statement; the data set defined 
by the unnamed DD statement would then be 
concatenated to the data set that was 
redefined by overriding. 

Note that any number of libraries could 
be concatenated to the SYSLIB data. set. . 
For example: 



• Unnamed DD statements can be placed 
after a statement containing the DDNAME 
parameter (indicating concatenation) , 
but unnamed DD statements cannot be 
placed after a statement referred to by 
a DDNAME parameter. 

• The DDNAME parameter can be used a 
maximum of five times in a step, but 
each DDNAME parameter must refer to a 
different statement. 

• The DDNAME parameter cannot be used in 
a JOBLIB statement. 



//LKED. SYSLIB DD 
// DD 

// DD 



DSNAME=USERLIB, DISP=OLD 
DSNAME=MYLIB, DISP=OLD 



When using the DDNAME parameter, the 
programmer should also keep the following 
in mind: 



USING THE DDNAME PARAMETER 



The DDNAME parameter is used to define a 
dummy data set that can assume the 
characteristics of an actual data set, 
defined by a subsequent DD statement within 
the step. If a matching DD statement is 
found, its characteristics, with the 
exception of its ddname, replace those of 
the statement using the DDNAME parameter. 
If a matching DD statement is not found 
within the step, the data set defined by 
the DDNAME parameter remains a dummv. 



• The name of the DD statement referred 
to does not replace the name of the 
referencing statement. 

• If a statement that contains the DDNAME 
parameter is overridden, it is 
nullified. 

• If overriding is performed with a 
statement that contains the DDNAME 
parameter, all parameters in the 
overridden statement are nullified. 



The following DD statements 



This section contains examples showing 
the use of the DDNAME parameter with 
cataloged procedures. 



The rules for using the DDNAME parameter 
are as follows: 

• A backward reference (e.g., *. ddname) 
to a DD statement referred to by a 



//SI 
//Dl 
//D2 
//D3 



EXEC PGM=progname 

DD DDNAME=D3 

DD (parameters X, Y, Z) 

DD (parameters U,T,V) 



will result in the same data definition 
produced by the following statements: 



//SI 
//Dl 
//D2 



EXEC PGM=progname 

DD (parameters U,T,V) 

DD (parameters X, Y, Z) 
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EXAMPLES OF USING THE DDNAME PARAMETER 



E xam p le 1 : The following example shows how 
to override the first DD statement in a 
cataloged procedure with a DD * statement, 
and allow subsequent statements to be proc- 
essed. Without the DDNAME parameter, 
replacing the first DD statement with a DD 
* statement would terminate processing of 
subsequent statements in the job step. The 
cataloged procedure (PR0C3) is as follows: 



Examp_le_3: The following example shows how 
to concatenate a data set in the input 
stream with a data set defined by a DD 
statement in a cataloged procedure. The 
cataloged procedure (PR0C3) is as follows: 



//STEP1 EXEC PG.M=progname 

//DDl DD (any parameters except 

DATA or *) 
//DD2 DD (any parameters except 

DATA or *) 



//STEP1 EXEC PGM=progname 

//DDl DD (any parameters except 

DATA or *) 
//DD2 DD (any parameters except 

DATA or *) 



The job procedure in wnich the 
concatenation takes place appears in the 
input stream as follows: 



The job procedure in which the overriding 
takes place appears in the input stream as 
follows: 



//J0B3 JOB 1234, J. SMITH 

//SI EXEC PR0C3 

//STEP1.DD1 DD (blank operand field) 

// DD DDNAME=DD3 

//DD3 DD * 



//J0B1 JOB 1234, J. SMITH 

//SI EXEC PR0C3 

//STEP1.DD1 DD DDNAME=Dl 

//Dl DD * 



The STEP1.DD1 statement overrides the 
DDl statement; the DD2 statement is proc- 
essed; then the Dl statement is processed. 



The data set in the input stream is 
concatenated with the data set defined by 
the DDl statement after the DD2 statement 
has been processed. 



Example 2: The following example shows how 
to override the first DD statement in a 
cataloged procedure with a DD * statement 
and how to add a DD statement. The 
cataloged procedure (PR0C3) is as follows: 



Examp_le_4: The following example shows how- 
to concatenate a data set in the input 
stream with a data set defined by a DD 
statement in a cataloged procedure and how 
to add a DD statement. The cataloged 
procedure (PR0C3) is as follows: 



//STEP1 EXEC PGM=progname 

//DDl DD (any parameters except 

DATA or *) 
//DD2 DD (any parameters except 

DATA or *) 



//STEP1 EXEC PGM=progname 

//DDl DD (any parameters except 

DATA or *) 
//DD2 DD (any parameters except 

DATA or *> 



The job procedure in which the overriding 
takes place appears in the input stream as 
follows: 

//J0B2 JOB 1234, J. SMITH 
//SI EXEC PR0C3 
//STEP1.DD1 DD DDNAME=DD4 
//STEP1.DD3 DD (any parameters except 

DATA or *) 
//DD4 DD * 



The DD4 statement effectively overrides 
the DDl statement, after the DD2 statement 
has been processed and the DD3 statement 
has been added. 



The job procedure in which the concate- 
nation takes place appears in the input 
stream as follows: 



//J0B4 JOB 

//SI EXEC 

//STEP1.DD2 DD 

// DD 

//STEP1.DD3 DD 



//DD4 



DD 



1234, J.SMITH 
PR0C3 

(blank operand field) 
DDNAME=DD4 

(any parameters except 
DATA or *) 
* 
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Example 5 : The following example shows how 
the statement DD DDNAME=SYSIN in the 
IBM- supplied COBUCLG procedure can be used 
to add more object modules as input to the 
linkage editor. The statements appear in 
the input stream as follows: 



//jobname 
//stepname 



JOB 
EXEC 



1234, J. SMITH 
COBUCLG 



//COB.SYSIN DD * 

(source deck) 

/* 

//LKED. SYSIN DD * 

(first object module) 



The COBUCLG procedure contains the 
following two statements in the linkage 
edit step: 



//SYSLIN DD DSNAME=£SLOADSET, 
// DISP= (OLD, DELETE) 

// DD DDNAME=SYSIN 



The result of concatenating SYSIN with 
SYSLIN is that when SYSLIN (input to 
linkage editor) is read, SYSIN is also read 
and linked with it- For example, if 
ILBODSPO is one of the object modules in 
the SYSIN stream, it will be linked with 
SYSLIN. The ILBODSPO module from 
SYS1.C0BLIB will not be used. 



(last object module) 
/* 
(//GO. cards) 
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USING THE SORT FEATURE 



In order to use the IBM System/360 
Operating System Sort/Merge program, Sort 
feature statements are written in the COBOL 
source program. These statements are 
described in the publication IBM OS Full 
A merican National Standard COBO L. The 
Sort/Merge program itself is described in 
the publication IB M O S Sort/Merge . In this 
publication, the system reguirements when 
the Sort feature is used are discussed in 
"Machine Considerations. " 

DD statements must be written in the 
execution-time job steps of the procedure 
to describe the data sets used by the sort 
program. DD statements for data sets used 
during the sort process are described in 
the section "Sort DD Statements." 

Note : The Sort/Merge Checkpoint Restart 
feature is available to the programmer who 
uses the COBOL SORT statement through the 
use of the RERUN statement. 



SORT DD STATEMENTS 



Three types of data sets can be defined 
for the sort program in the execution time 
job step: input, output, and work. In 
addition, data sets must be defined for the 
use of the system during the sorting 
operation. 



SORT INPUT DD STATEMENTS 



The input data set is associated with a 
ddname that appears as the ddname portion 
of the system-name in an ASSIGN clause in 
the COBOL source program. When the USING 
option is specified, the compiler will 
generate an input procedure that will open 
the data set, read the records, release the 
records and close the data set. 



SORT OUTPUT DD STATEMENTS 



The output data set is associated with a 
ddname that appears as the ddname portion 
of the system-name in an ASSIGN clause in 
the COBOL source program. When the GIVING 
option is specified, the compiler generates 
an output procedure that will open the data 
set, return the records, write the records, 
and close the data set. 



SORT WORK DD STATEMENTS 



-ffh-e- ^ort program require sat least thre e 
w^fk— 4 ata se ts. The ddname~Tof^eacTTDD 
statement is in the form SORIWKnn, where nn 
is a decimal number. The ddnames for the 
reguired data sets must be SORTWK01, 
SORTWK02, and SORTWK03. Additional work 
data sets may be defined, but their ddnames 
must be consecutively numbered, beginning 
with 04. 



SORTWKnn Data Set Considerations 



Intermediate data sets (i.e., SORTWKnn 
data sets) for a sort may be assigned to 
either magnetic tape or mass storage 
devices. All of the intermediate storage 
for one sort must be assigned to the same 
device type. These may not be on Doth 
7-track and 9-track tape units in the same 
sort. Any one of the following devices may 
be used for intermediate storage: 

IBM 2400-series Magnetic Tape Unit 

(7-track) 
IBM 2400-series Magnetic Tape Unit 

(9-track) 
IBM 2311 Disk Storage Drive 
IBM 2301 Drum Storage 
IBM 2305 Fixed Head Storage, Models 1 

and 2 1 
IBM 3330 Disk Storage 1 

The publication I BM OS Sort/Merge contains 
detailed information about these devices. 

Since spanned records can be input to 
and output from the sorting operation, it 
is the user's responsibility to assign the 
sort work files to mass storage devices 
whose track sizes are larger than the 
logical record size of the records being 
sorted. An S-mode file whose logical 
record length is greater than its track 
size may be sorted by assigning the work 
files to a magnetic tape unit. 

If data sets not involved in the sorting 
operation are assigned to tape units, these 
tape units may be used as sort work files 
by using the UNIT=AFF parameter. For 
example, if PAYROLL is specified as the 



^The programmer should be sure that the 
sort program selected supports these new 
devices. 
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ddname of the ASSIGN clause in a SELECT 
statement, the tape unit assigned to 
PAYROLL could be used as a sort work file 
by using the following DD statement: 

//PAYROLL DD UNIT=2400, 

//SORTWK02 DD UNI T=AFF= PAYROLL. . . 



SORTWKnn DD Statements 



SORTWKnn data sets may be contained on 
tape or mass storage volumes. When mass 
storage space is assigned, only the primary 
allocation is used by the sort, and it must 
be contiguous. 

Note that the SORTWKnn data sets: 



Input DD Statement 



The input data set must reside on a 
physical device, a magnetic tape unit, a 
mass storage device, or in the system input 
stream. The following example shows DD 
statement parameters that could be used to 
define a cataloged input data set. 



//INSORT DD DSNAME=INPT, 

// DISP= ( OLD, DELETE ) 



X 



1. May not be on 7-track tape when the 
input data set is on 9-track tape. 

2. May be on 7-track tape when the 
output data set is on 9-track tape. 

3. Cannot use the data conversion feature 
if they are on 7-track tape. The 
TRTCH subparameter must reflect this. 

4. May be on 9-track tape when the input 
data set is on 7-track tape. 



These parameters cause the system to search 
the catalog for a data set named INPT 
(DSNAME parameter). When found, the data 
set is associated with the ddname INSORT 
and used by the sort program. The control 
program obtains the unit assignment and 
volume serial number from the catalog, and 
displays- a mounting message to- the 
operator. The DISP parameter indicates 
that the data set has already been created 
(OLD). It also indicates that the data set 
should be deleted (DELETE) after the 
current job step. 



Output DD Statment 



SOR TWKnn Example A : The following DD 
statement parameters ' could be used to 
define a tape intermediate storage data 
set: 



//SORTWK01 DD 
// 



UNIT=2400, LkBEL=(,WL) , 
-VOLUME=SER=; DUMMY- - 



These parameters specify an unlabeled data 
set on a 2400-series tape unit. Since the 
DSNAME parameter is omitted, the system 
assigns a unique name to the data set. The 
omission of the DISP parameter causes the 
system to assume that the data set is new 
and that it should be deleted at the end of 
the current job step. The 2400-series tape 
units are explicitly of the 9-track format. 



The output DD statement must define all 
of the characteristics of the output data 
set. The following example shows DD 
statement parameters that could be used to 
characterize an output data set: 



//OUTSORT DD DSNAME=OUTPT, UNIT=2400, 
// DISP=(NEW, CATLG) 



X 



The DISP parameter indicates that the data 
set is unknown to the o r ^eratin rr s ,7 ste rr i 
(NEW) and that it should be cataloged 
(CATLG) under the name OUTPT (DSNAME 
parameter). The UNIT parameter specifies 
that the data set is on a 2400-series tape 
unit. 



SORTWKn n Ex ample B: The following DD 
statement parameters could be used to 
define a mass storage intermediate storage 
data set: 



//SORTWK01 DD 
// 



UNIT=SYSDA, X 

SPACE=(TRK, (200) , , CONTIG) 



These parameters specify a mass storage 
data set with a standard label (LABEL 
parameter default value) * The SPACE 
parameter specifies that the data set is to 
be allocated 2 00 contiguous tracks. The 
system assigns a unique name to the data 
set and deletes it at the end of the job 
step. 
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ADDITIONAL DD STATEMENTS 



SORT PROGRAM EXAMPLE 



The sort program requires two additional 
DD statements: 

//SYSOUT DD SYSOUT=A 

which defines the system output data set. 

//SORTLIB DD DSNAME=SYS1. SORTLIB r X 
// DISP=SHR 

which defines the library containing the 
SORT modules. 

Note: At system generation time, 
theprogrammer can designate that SORT 
diagnostic messages be printed either on 
the console or on the unit designated 
SYSOUT. If the system is generated to 
write SORT messages on SYSOUT, these 
messages may overprint any COBOL output 
assigned to SYSOUT. For example, if the 
programmer has selected SYSOUT on which to 
print a report in the output procedure 
associated with the execution of the COBOL 
SORT statement, any SORT messages will be 
interspersed within that report. If it is 
not possible to assign the SORT messages to 
the console, the programmer should assign 
his COBOL output to temporary files and 
print the reports at a later time. 



SHARING DEVICES BETWEEN TAPE DATA SETS 



A single tape unit may be assigned to 
two sort data sets when the data sets are 
one of the following pairs: 

• The input data set and the first 
intermediate storage data set 
(SORTWK01). 



The input data set and the output data 
set. 

The AFF subparameter of the UNIT 
parameter can be used to associate the 
input data set with either the SORTWK01 
data set or the output data set. The 
subparameter can appear in the DD statement 
for SORTWK01 or output. 



The control cards in Figure 104 could be 
used with the sample program that 
illustrates the Sort feature. A 
description of the Sort Feature can be 
found in the publication IBM_OS_Full 
American National Standard COBOL. 



//SORTEST 


JOB 


NY838670165, 


X 


// 




' J. SMITH' , 


X 


// 




MSGLEVEL=1 




//SORTJS3 


EXEC 


COBUCLG 




//COB. SYSIN 


DD 


* 





(COBOL source program) 



| //GO. SORTWK01 


DD 


UNIT=2311, 


X 


|// 




SPACE=(TRK, (200) , 


X 


|// 




, CONTIG) 




|//GO.SORTWK02 


DD 


UNIT=2311, 


X 


|// 




SPACE=(TRK, (200) , 


X 


|// 




, CONTIG) 




|//GO.SORTWK03 


DD 


UNIT=2311, 


X 


|// 




SPACE=(TRK, (200) , 


X 


|// 




, CONTIG) 




| //GO. OUTSORT 


DD 


UNIT=183, 


X 


|// 




LABEL=(,NL), 


X 


|// 




VOLUME=SER=NONE 




| //GO. SYSOUT 


DD 


SYSOUT=A 




| //GO. SORTLIB 


DD 


DSNAME=SYS1. SORTLIB 


,x 


|// 




DISP=SHR 




|//GO.INFILE 


DD 


UNIT=182, 


X 


|// 




LABEL=(,NL), 


X 


L _ 




VOLUME=SER=DUMMY 




Figure 104. Sort 


Feature Control Cards 





The minimum number of SORTWKnn data sets 
are used; the sort operation can be 
optimized by using additional work data 
sets (see the publication IBM Syst em/360 
Oper ating System: Sort/Merge ) . 



CATALOGING SORT DD STATEMENTS 



USING MORE THAN ONE SORT STATEMENT IN A JOB 



More than one SORT statement may be used 
in a single program or in two or more 
programs that are combined into a single 
load module. 



Since repeated use of the Sort feature 
often involves the same execution time DD 
statements, the user may wish to catalog 
them (see "Using the Cataloged 
Procedures") . 

When using the COBOL RERUN feature, all 
SORT messages are written on the console. 
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LINKAGE WITH THE SORT/MERGE PROGRAM 



Communication between the Sort/Merge 
program and the COBOL program is maintained 
by the COBOL library subroutine ILBOSRTO. 
The programmer must designate via the 
appropriate SORTLIB DD statement the 
Sort/Merge program he wishes to use. 

If the INPUT PROCEDURE option of the 
SORT statement is specified, exit E15 of 
the Sort/Merge program is used. The return 
code indicating "insert records" is issued 
when a RELEASE statement is encountered, 
and the return code indicating "do not 
return" is issued when the end of the 
procedure is encountered. 

If the OUTPUT PROCEDURE option is 
specified, exit E3 5 of the Sort/Merge 
program is used. The return code 
indicating "delete records" is issued when 
a RETURN statement is encountered, . and the 
return code indicating "do not return" is 
issued when the end of the procedure is 
encountered. (For additional information, 
about the Sort/Merge program, see the 
publ i c a t i on IBM OS Sort/Merge ) . 



then be tested for and appropriate action 
specified. Note that the contents of 
SORT-RETURN will change with the execution 
of a SORT statement. The following is an 
example of the use of SORT-RETURN with the 
sort feature: 

SORT SALES-RECORDS ON ASCENDING KEY 
CUSTOMER- NUMBER, DESCENDING KEY DATE, 
USING FN-1, GIVING FN- 2. 

IF SORT-RETURN NOT EQUAL TO ZERO, 
DISPLAY 'SORT UNSUCCESSFUL' UPON 
CONSOLE. STOP RUN, 

If no references to SORT-RETURN are made in 
a program, an unsuccessful sort will 
generate the following message: 

IKF888I- UNSUCCESSFUL SORT FOR SD 
SORT-FILE DDNAME 



See the publication IBM OS Full Am erican 
Natio na l Standard C O BOL Ver si on 4 Messages, 
for a description of action to be taken. 



LOCATING SORT RECORD FIELDS 



Completion codes 



The Sort/Merge program returns a 
completion code upon termination. This 
code may be interrogated by the COBOL 
program. The codes are: 



Records defined under a COBOL SD are 
assigned —a - BLL ( Base- Locator for Linkage - 
Section), rather than a BL (Base Locator) 
as is done witn other records. Location of 
a given data item in an object-time dump 
when the record in which it is contained 
references a BLL can be determined as 
follows: 



— Successful completion of 
Sort/Merge 
16 — Unsuccessful completion of 
Sort/Merge 



1. From the compilation listing, 
determine : 

a. The displacement of the item (see 
Data Division Map) . 



SUCC ESSFUL COMPLETION : When a Sort/Merge 
application has been successfully executed, 
a completion code of zero is returned and 
the sort terminates. 



b. The relative address of the BLL 
CELLS (see the Memory Map Table). 

c. The BLL number. 



UNSUCCESSFUL COMPLETION : If the sort, 2. 

during execution, encounters an error that 

will not allow it to complete successfully, 

it returns a completion code of 16 and 

terminates. (Possible errors include an 3. 

out-of-seguence condition or an 

input/output error that cannot be 

corrected. ) The publication IBM O S 

Sort/ Merge contains a detailed description 

of the conditions under which this 

termination will occur. 4. 

The returned completion code is stored 
in a special register called SORT-RETURN by 
the COBOL library subroutine; an 
unsuccessful termination of the sort may 



From the dump, determine the 
relocation factor (USE/EP). 



Add the relative address of the BLL 
CELLS to the relocation factor to 
obtain the absolute BLL CELLS address 
in the dump. 



Each BLL is 4 bytes long; they are 
located in ascending sequence; 
beginning in the dump at the address 
computed in Step 3 BLL=1 is the first 
4 bytes, BLL=2 is the second 4 bytes, 
etc. Find the appropriate 4 bytes. 
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5. The 4 bytes obtained in Step 4 contain 
the absolute base address of the 
desired record. Add the item' s 
displacement to it to obtain the 
absolute address of the leftmost byte 
of the field in the dump. 



When you do not supply information such as 
data set size and record format, trie 
program must make assumptions, which, if 
incorrect, lead to ineffiency. 



DATA SET SIZE 



LOCA TING LAST RECORD RELEASED TO SORT BY AN 
INPUT PROCEDURE 



For debugging purposes, it is sometimes 
useful to determine the last input record 
released to the Sort program. The 
following procedure should be used: 

1. From the Data Division map, determine 
the BLL number of the SORT file being 
processed at the time of program 
termination. Assume it is BLLn. 

2. From the Task Global Table map, 
determine the location of the BLL 
cells in the COBOL object program. 

3. The nth BLL in the core dump will 
point to the last record released to 
SORT. 



The most important information one can 
give is an accurate data set size using the 
SORT-FILE-SIZE special register. If the 
exact number of records in the input data 
set is known, that number should be used as 
the value. If the exact number is not 
known, an estimate should be made. 



When the Sort/Merge program has accurate 
information about data set size, it can 
make the most efficient use of botn main 
storage and intermediate storage. Unless 
the Sort/Merge Program Product (SMI) is 
installed, the SORT-FILE-SIZE special 
register has no effect when the sort work 
data sets are on disk. When SMI is used, 
accurate specification of SORT-FILE-SIZE is 
the only way the SMI performance benefits 
are reached. 



Note ; This BLL is initialized when control 
is first transferred to the input 
procedure. Thus, if the program terminates 
before control ever goes to the input 
procedure, the BLL will not be initialized. 



SORT/MERGE CHECKPOINT/RESTART 



The CHECKPOINT/RESTART feature is 
available to the programmer using the COBOL 
SORT statement. In order to initiate a 
checkpoint, the programmer uses DD 
statements and the RERUN clause. The DD 
statement for use in taking a checkpoint is 
discussed in "Using the Checkpoint/Restart 
Feature. " 

The RERUN clause is used to indicate 
that checkpoints are written, at logical 
intervals determined by the sort program, 
during the execution of all SORT statements 
in the program. This RERUN clause is fully 
described in the publication IBM OS Full 
American National Standard COBOL. 



EFFICIENT PROGRAM USE 



The information you give the Sort/Merge 
program about the application it is to 
perform helps the sort and merge phases to 
produce a fast, efficient sort or merge. 



MAIN STORAGE REQUIREMENTS 



If the maximum amount of main storage to 
be used by the Sort/Merge program was not 
specified at system generation time for SM 
(the OS Sort/Merge Program -- Program No. 
360S-SM-023) or at installation time for 
SMI (the Program Product Sort/Merge — 
Program No. 5734-SMl), the program assumes 
a maximum of 15,500 bytes. The sort 
program requests 12,000 bytes leaving 3500 
bytes for system functions. Performance 
usually improves as the program is given 
more main storage. Approximately 44K oytes 
of main storage are needed for efficient 
execution of the sort/merge program, and 
performance increases as more main storage 
is made available. 



If the amount of main storage was 
specified at system generation time, it is 
the programmer's responsibility to ensure 
that the Sort/Merge program has at least 
that much core storage available in 
addition to the space needed for Data 
Management and the COBOL program. If this 
amount of core storage is not available, 
the program will terminate abnormally. 

The programmer may alter, dynamically 
within the COBOL program, the core storage 
default values for the Sort/Merge program. 
The SORT-CORE-SIZE special register may be 
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used to communicate changes to the 
Sort-Merge program. In general, a positive 
value placed in SORT-CORE-SIZE denotes the 
amount of storage the programmer is 
allocating for use by the Sort/Merge 
program. For example, the statement "MOVE 
30000 TO SORT-CORE-SIZE" means that 30000 
bytes of storage are available to the 
Sort/Merge program. 

Special considerations apply when SMI is 
used. If the program product is installed 
with the C0RE=MAX option, SMI allocates all 



at7ai 1 =s V\~\ £± /-*r\-i 



nr. -£,->-*- 



own use. If an input procedure then 
attempts to open a file, an 8 0A abnormal 
termination may result if the necessary 
data management modules have not already 
been loaded, or are not resident in the 
link pack area (LPA), since no more space 
is available. Accordingly, if 30000 is 
moved to SORT-CORE-SIZE, COBOL communicates 
to SMI that 30000 bytes of storage are 
available to it. There are, in addition, 
two other uses for SORT-CORE-SIZE. 



When the Sort/Merge program is 
installed, the user can elect to have 
messages sent to the printer, in which case 
a DD card with a ddname of SYSOUT must De 
included in the job step. If SMI is used, 
the programmer can dynamically alter the 
ddname of the file on which SMI is to write 
its messages. If SMI has been installed 
with provision for routing its messages to 
the printer, then the programmer can place 
in the SORT-MESSAGE special register the 
ddname that SMI is to substitute for 
SYSOUT, for message routing. For example, 

n^^ n 4- !*-> /-* «-» 4 i4*/\mAMj- s/i^ttti If <"■ r\n -nrM- * tvtrx n -nr-\ 
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SORT-MESSAGE is executed before an SMI sort 
is initiated, then the SMI sort writes its 
printer messages to the data set SORIDDWM 
rather than to SYSOUT. If SORT-MESSAGE is 
not referred to in the program, SYSOUT is 
the default value. 

One technique for specifying the sort 
print file ddname would be to include 
source language and joio control language 
statements as follows: 



If a negative value is placed in the 
special register prior to execution of the 
sort, SMI uses the default CORE option 
specified at installation, but sets aside 
that absolute value before obtaining the 
CORE SIZE installed. Also, if ALL r 9' (or 
+9999^9) i.- moved to SORT-CORE-SIZE prior 
to a sort operation, SMI executes with the 
CORE=MAX option, regardless of the 
installed value, while reserving 6K bytes 
of main storage for use by the data 
management routines. (For additional 
information about the Sort Feature options, 
see the Program Product publication IBM OS 
S ort /Merge Programmer ' s Guide , Order No. 
SC33-4007. ) 



* Lin!i§:2§_Section 

01 SORT- PARAMETERS. 

05 PARAMETER- COUNT PIC 9(4) USAGE COMP. 

05 SORT-DDNAML PIC X(8). 

'•" "Immedia te l y preceding ""the sor t 
oper ation 

IF PARAMETER- COUNT IS NOT EQUAL 10 
MOVE SORT-DDNAME TO SORT-MESSAGE. 

• On the E XEC card 

//GOSTEP EXEC PGM=program-name, 
PARM= ' SORTDDNM' 



Changing the main storage allocation can 
be useful when a sort-merge application is 
to be run in a multiprogramming 
environment. By reducing the amount of 
main storage allocated to sort, so that 
other programs can have the storage they 
need to operate simultaneously, the 
performance of sort is impaired. However, 
if this allocation is increased, so that a 
large sort application runs more 
efficiently, the performance of other jobs 
sharing the multiprogramming environment is 
impaired, if not made altogether 
impossible. 



SORT DIAGNOSTIC MESSAGES 



The messages generated by the Sort 
Feature are listed in the publication I BM 
OS So rt/Merge and IB M OS Messages and 
C ompletion Codes . The identifying 
characters in a sort message are IER. 



Note: This technique of assigning a unique 
value to SORT-MESSAGE without modifying or 
recompiling the program can also be applied 
to the special registers SORT-CORE-SIZE, 
SORT-MODE-SIZE, and SORT-FILE-SIZE. 



DEFINING VARIABLE-LENGTH RECORDS 



If the input records used are of 
variable length, the record length tnat 
occurs most frequently in the input data 
set (modal length) should be put into the 
special register SORT-MODE-SIZE. This 
value is used to help define a data set 
based on a particular length. If a value 
is not specified, the SORT program assumes 
it is equal to the average of the maximum 
and minimum record lengths in the input 
data set. If, for example, the data set 
contains mostly small records and just a 
few long records, the SORT program would 
assume a high modal length and would 
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allocate a larger record storage area than 
necessary. Conversely, if the data set 
contains just a few short records and many 
long records, the SORT program would assume 
a low modal length and might not allocate a 
large enough record storage area to sort 
data- For a complete discussion, see the 
publication IBM OS So rt/Merge Program. 



AA. The correct length of this 
receiving field must be set before the 
move, but use of the GIVING option 
precludes this. To avoid error, the 
user should substitute an output 
procedure for the GIVING option, as in 
section PARA3B of the example. 



SORTING VARIABLE- LENGTH RECORDS 



TERMINATING A SORT OPERATION 



Figure 105 illustrates one way to sort 
variable-length records described by the 
OCCURS clause with the DEPENDING ON option. 
If the FD's (file-name description) and the 
SD' s (sort-file-name description) are 
defined as in this figure, where the record 
descriptions of the FD* s and the SD 
correspond, possibilities for error arise. 
It is suggested, therefore, that the user 
consider the following: 

1. Specification of the statement 

SORT SORT-FILE USING INPUT-FILE. . . 

would probably lead to incorrect 
results. This statement implies a 
READ ... INTO ... statement; that 
is, after INPUT-FILE has been read, 
the record is moved to AAA. However, 
because the user must set the length 
of this receiving field prior to 
moving A to AAA but cannot do so, the 
compiler may use an incorrect length 
that results in abnormal termination. 
Instead, the user should substitute an 
input procedure for the USING option, 
as in the section of code labeled 
PARA2B in the example. 

2. Similarly, the statement 

SORT SORT-FILE. . . GIVING OUTPUT-FILE 

would probably yield incorrect 
results. Before OUTPUT-FILE is 
written out, the record is moved to 



The SORT-RETURN special register can 
also be used to terminate an SMI sort 
operation. If the programmer places the 
value 16 in this special register at any 
point during an input or output procedure, 
the sort is terminated immediately after 
execution of the next RELEASE or RETURN 
statement. 

Note ; Once a value has been placed in a 
sort special register and the SORT 
statement has executed, this value is used 
(even if the special register is modified 
during the sort operation) until another 
sort is initiated. The one exception to 
this rule is in the use of the special 
register SORT-RETURN, which is set to zero 
at the beginning of each sort. 



SORT FOR ASCII FILES 



For sorting ASCII files, the normal 
EBCDIC collating sequence is provided 
unless the user specifies otherwise on a 
per sort basis. 

To specify a sort using the ASCII 
collating sequence, the programmer must 
include the "C" organization entry in the 
ASSIGN clause for the file-name associated 
with the file to be sorted. No buffer 
offset may be given with the sort feature. 

Note : The SMI program is required for 
sorting a file using the ASCII collating 
sequence. 
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Part 1 



Part 2 



IDENTIFICATION DIVISION. 
PROGRAM-ID. VLSORT. 
ENVIRONMENT DIVISION. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT * • . • 

SELECT .... 

SELECT • . • • 

DATA DIVISION. 

FILE SECTION. 

FD INPUT-FILE. 

LABEL RECORDS ARE OMITTED 
DATA RECORD IS A. 
01 A. 

02 B PIC 99. 

02 C OCCURS 1 TO 10 TIMES 
DEPENDING ON B. 
03 D PIC 99. 
03 E PIC XX. 
FD OUTPUT-FILE 

LABEL RECORDS ARE OMITTED 
DATA RECORD IS AA. 
01 AA. 

02 BB PIC 99. 
02 CC OCCURS 1 TO 10 TIMES 
DEPENDING ON BB. 
03 DD PIC 99. 
03 EE PIC XX. 
SD SORT-FILE 

DATA RECORD IS AAA. 
01 AAA. 

02 BBB PIC 99. 
02 CCC OCCURS 1 TO 10 TIMES 
DEPENDING ON BBB. 
03 DDD PIC 9 9. 
03 EEE PIC XX. 



PROCEDURE DIVISION. 
PARI SECTION. 

SORT SORT-FILE ASCENDING KEY BBB. 

INPUT PROCEDURE PAR2 

OUTPUT PROCEDURE PAR3. 
STOP RUN. 
PAR2 SECTION. 
PAR2A. 

OPEN INPUT INPUT-FILE. 
PAR2B. 

READ INPUT-FILE AT END GO TO PAR2C. 

MOVE B TO BBB. 

RELEASE AAA FROM A. i 

GO TO PAR2B. 
PAR2C. 

CLOSE INPUT-FILE. 
PAR2-EXIT. 

EXIT. 
PAR3 SECTION. 
PAR3A. 

OPEN OUTPUT OUTPUT-FILE. 
PAR3B. 

RETURN SORT- FILE AT END GO TO PAR3C. 2 

MOVE BBB TO BB. 

WRITE AA FROM AAA. 

GO TO PAR3B. 
PAR3C. 

CLOSE OUTPUT-FILE. 
PAR3-EXIT. 

EXIT. 



i-When using a sort input procedure, the RELEASE . . . FROM clause, which implies a MOVE 

and then a RELEASE, should always be preceded by a MOVE that sets the length of the 

receiving field (AAA, in this example) . 
2 When using a sort output procedure, the RETURN . . . INTO . . . clause, which implies 

the RETURN and then a MOVE, should n ever be used. There is no way for the user to set 

the correct length of the receiving field. 

Figure 105. Sorting Variable-Length Records Whose File-name Description and 
Sort-File-name Description Correspond 
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USING THE SEGMENTATION FEATURE 



Segmentation provides a means of 
accomplishing obiect time overlay as a 
result of specifications made at the source 
language level. The programmer may divide 
the Procedure Division of a source program 
into sections. Through the use of a system 
of priority numbers, certain sections are 
designated as permanently resident in core 
and other sections as overlayable fixed 
segments and/or independent segments. 
Thus, a large program can be executed in a 
defined area of core storage by limiting 
the number of segments in the program that 
are permanently resident in core storage. 



are those assigned priority numbers greater 

tnan 4" and icao uuan xuu. llieibe 

independent segments are returned to their 
initial state when they are Drought into 
core storage. 



IDENTIFICATION DIVISION. 
PROGRAM-ID. SAVECORE. 



N ote : The segmentation feature is not 
available when the loader is used. 



ENVIRONMENT DIVISION. 



Suppose that because of core storage 
limitations the program SAVECORE is 
segmented as shown in Figure 106. Only 
those segments having priority numbers less 
than the segment limit of 15 are designated 
as permanently resident. 



OBJECT-COMPUTER. IBM-360-h50 
SEGMENT-LIMIT IS 15. 



DATA DIVISION. 



Assuming that 12K is available for the 
program SAVECORE, Figure 107 shows that 
manner in which core storage would be 
utilized. Sections 3 and 6, and sections 5 
and 7 are considered logical units since 
they have the same priority numbers. 
Sections 3 and 6 can be in core together, 
but section 7 cannot be there at the same 
time. Similarly, sections 5 and 7 can be 
in core together, but section 3 cannot be 
there at the same time. 

Sections in the permanent segment 
(SECTION-1, SECTION-2, and SECTION-4) are 
those that must be available for reference 
at all times, or those to which reference 
is made frequently. They are distinguished 
here by the fact that they have been 
assigned priority numbers less than the 
segment limit. 



PROCEDURE DIVISION. 
SECTION-1 SECTION 8. 



SECTION-2 SECTION 8. 



SECTION- 3 SECTION 16, 



SECTION-4 SECTION 8. 



SECTION- 5 SECTION 50. 



Sections in the overlayable fixed 
segment are sections that are less 
frequently used. These sections are always 
made available in the state in which they 
were last used. They are distinguishable 
here by the fact that they have been 
assigned priority numbers greater than the 
segment limit, but less than 50. 



SECTION- 6 SECTION 16. 



SECTION-7 SECTION 50. 



Sections in the independent segment can 
overlay, and be overlaid by, either an 
overlayable fixed segment or another 
independent segment. Independent segments 



L J 

Figure 106. Segmentation of Program 
SAVECORE 
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Total 
Available 
Core 
Storaae 
(12IO 



Fixed 

portion 

<7K) 



Core 

Storage 

Available 

for 

Overlay 

(5K) 



data-buffers, global table, 
etc. (Ik) 



SECTION-1 
SECTION- 2 
SECTION- 4 
SECTION- 3 



(2K) 
(2K) 
(2K) 
(3K) 




control information 

(permanently in 

core storage) 



permanent segment 

(segment limit < 15) 



SECTION-5 (2K) 



SECTION-6 (2K) 




SECTION-3 and SECTION-6 

are overlayable fixed 

segments 

(14 < segment limit < 50) 



SECTION-5 and SECTION- 7 
are independent segments 
(49 < segment limit < 100) 



Figure 107. Storage Layout for SAVECORE 



USING THE PERFORM STATEMENT IN A SEGMENTED 
PROGRAM 



When the PERFORM statement is used in a 
segmented program, the programmer should be 
aware of the following: 

• A PERFORM statement that appears in a 
section whose priority-number is less 
than the segment limit can have within 
its range only (a) sections with 
priority-numbers less than 50, and (b) 
sections wholly contained in a single 
segment whose priority-number is 
greater than 49. 



Note: 



As an extension to American 



National Standard COBOL, the OS Full 
American National Standard COBOL 
Compiler allows sections with any 
priority- number to fall within the 
range of a PERFORM statement. 

A PERFORM statement that appears in a 
section whose priority-number is equal 
to or greater than the segment limit 
can have within its range only (a) 
sections with the same priority-number 
as the section containing the PERFORM 



statement, and (b) sections with 
priority-numbers that are less than the 
segment limit. 

Note: As an extension to American 
National Standard COBOL, the OS Full 
American National Standard COBOL 
Compiler allows sections with any 
priority-number to fall within the 
range of a PERFORM statement. 

When a procedure-name in a segment with 
a priority-number less than the segment 
limit referred to by a PERFORM 
statement in a segment with a 
priority-number greater than the 
segment limit, the independent segment 
will be reinitialized upon exit from 
the PERFORM. 



OPERATION 



Execution of the object program begins 
in the root segment; i.e. , the first 
segment in the permanent segment. If the 
program contains no permanent segments, or 
if the first section to be executed in the 
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program is not part of the root segment, 
the compiler generates a dummy segment that 
will initiate the execution of the first 
overlayable or independent segment. All 
global tables, literals, and data areas are 
part of the root segment. Called 
object-time subroutines are also part of 
the root segment. Called subprograms are 
loaded with the fixed portion of the main 
program and assigned a priority of zero. 
Otherwise, the program executes just as if 
it were not segmented. 

For a discussion on determining the 
priority of the last segment loaded into 
the transient area, see the section 
"Debugging a Segmented Program" in the 
chapter "Program Checkout". 



object modules preceded by linkage editor 
control statements. Segments whose 
priority is greater than the segment limit 
(or 49, if no SEGMENT-LIMIT clause is 
specified) consist of executable 
instructions only. The PMAP output is 
given in this sequence: all sections with 
priorities greater than the segment limit 
are listed first in ascending order by 
priority number, followed by the root 
segment. 

Figure 108 shows the output of a sample 
segmentation program. 



JOB CONTROL CONSIDERATIONS 



COMPILER OUTPUT 



The output produced by the compiler is 
an overlay structure consisting of multiple 



In order to execute a segmented program, 
the programmer must specify OVLY in the 
parameter field of the linkage editor EXEC 
statement. Note that when using the 
IBM-supplied cataloged procedures, the user 
must respecify the LIST and LET parameters. 
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00001 


000060 


00002 


000070 


00003 


000080 


00004 


000090 


00005 


000100 


00006 


000110 


00007 


000120 


00008 


000130 


00009 


000140 


00010 


000150 


00011 


000160 


00012 


000170 


00013 


000180 


00014 


000190 


00015 


000200 


00016 


000210 


00017 


000220 


00018 


000230 


00019 


000240 


00020 


000250 


00021 


000260 


00022 


000270 


00023 


000280 


00024 


000290 


00025 


000300 


0002o 


000310 


00027 


000320 


00028 


000330 


00029 


000340 


00030 


000350 


00031 


000380 


00032 


000390 


00033 


000400 


00034 


000410 


00035 


000420 


00036 


000430 


00037 


000440 


00038 


000450 


00039 


000460 


00040 


000470 


00041 


000480 


Q.0..Q42. ... 


_0.0.Q49_0. 


00043 


000500 


00044 


000510 


00045 


000520 


00046 


000530 


00047 


000540 


00048 


000550 


00049 


000560 


00050 


000570 


00051 


000580 


00052 


000590 


00053 


000600 


00054 


000610 


00055 


000620 


00056 


000630 


00057 


000640 



NONE. 



IDENTIFICATION DIVISION. 
PROGRAM-ID. SES-SAMPLE. 
AUTHOR. PROGRAMMER-NAME. 
REMARKS. 

SPECIAL OPERATOR INSTRUCTIONS 
INPUT REQUIRED - NONE. 
PURPOSE 

TO CREATE A SINGLE FILE ON DISK USING 
QSAM/DTFSD, AND READ IT BACK. 
PROGRAM OSES SEGMENTATION 
WITH FILE PROCESSING SPREAD OVER 
THE PERMANENT, OVERLAYABLE FIXED, 
AND INDEPENDENT SEGMENTS. 
EXPECTED RESULTS 

START TEST SEG-SAMPLE 

(EACH SEGMENT DISPLAYS ITS SEGMENT NUMBER 
AND FUNCTION) . 

END TEST SEG-SAMPLE SUCCESSFUL RUN 
SECTIONS WHILE WRITING APPEAR 
IN ORDER 80, 20, 30, 60, 40. 
SECTIONS WHILE READING APPEAR 
IN ORDER 80, 60, 30, 40, 20. 
ERROR INDICATIONS 

♦♦ERROR DISK SEQ I/O** 

**ERROR END OF EXTENT WRITING AFTER (RECORD)** 

♦♦ERROR UNEXPECTED EOF READING AFTER 

RECORD (RECNO) *♦ 
♦♦ERROR EOF NOT FOUND++ 
++RECOKD IS (RECNO) 

SHOULD BE (RECNO)** 
PROGRAM CONTAINS PERFORMS 
TO PERMANENT, OVERLAYABLE 
SEGMENTS. 

ALSO CONTAINS PERFORMS FROM INDEPENDENT TO PERMANENT 
AND FROM OVERLAYABLE FIXED TO PERMANENT SEGMENTS. 
ALSO CONTAINS PERFORMS ENTIRELY WITHIN A SEGMENT IN 
IN EACH CATEGORY. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE- COMPUTER. IBM-360-40. 
OBJECT-COMPUTER. IBM-360-40 

MEMQRY_._SIZE._640 00 .CHARACTERS 
SEGMENT-LIMIT 13 25. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO DA-2311-S-DKSQ01A. 
DATA DIVISION. 
FILE SECTION. 
FD FILE-1 

RECORDING MODE IS F 
LABEL RECORDS OMITTED 
DATA RECORD IS RECFD1* 
01 RECFD1 PICTURE X(83). 
WORKING-STORAGE SECTION. 
77 ERRORSW PIC A VALUE S^ACE. 
77 ERCTFL PIC 399 VALUE ZERO. 
77 MSGHDR PIC X(22) VALUE * ♦♦ERROR DISK SEQ I/O**'. 



FROM BASE SECTION 
FIXED, AND INDEPENDENT 



00154790 



00154820 
00154830 
00154840 
00154850 
00154860 
00154870 
00154880 
00154890 
00154900 
00154910 
00154920 

00154940 
00154950 

00154970 
00154980 
00154990 
00155000 
00155010 
00155020 
00155030 
00155040 
00155050 
00155060 
00155070 
00155080 
00155110 
00155120 
00155130 
00155140 
00155150 
00155160 
00155170 
00155180 
00155190 
00155200 
00155210 
00155220 
00155236 
00155240 
00155250 
00155260 
00155270 
00155280 
00155290 
00155300 



00155310 
00155320 
00155330 
00155340 
00155350 
00155360 



Figure 108. Sample Segmentation Program (Part 1 of 14) 
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Q00d8 
00059 
00060 
00061 
00062 
00063 
00064 
00065 
00066 
000b7 
00068 
00069 
00070 
00071 
00072 
00073 
00074 
00075 
00076 
00077 
00078 
00079 
00080 
00081 
00082 
00083 
00084 
00085 
00086 
00087 
00088 
00089 
00090 
00091 
00092 
00093 
00094 
00095 
00096 
00097 
00098 
00099 
00100 
00101 
00102 
00103 
00104 
00105 
00106 
00107 
00108 
00109 
00110 
00111 
00112 
00113 
00114 



000650 
000660 
000670 
000680 
000690 
000700 
000710 
000720 
000730 
000740 
000750 
000760 
000770 
000780 
000790 
000800 
000810 
000820 
000830 
000840 
000850 
000860 
000870 
000880 
000890 
000900 
000910 
000920 
000930 
000940 
000950 
000960 
000970 
000980 
000990 
001000 
001010 
001020 
001030 
001040 
001050 
001060 
001070 
001080 
001090 
001100 
001110 
001120 
001130 
001140 
001150 
001160 
001170 
001180 
001190 
001200 
001210 



77 MSGEOX PIC X»36> 

VALUE ' **ERROR END OF EXTENT WRITING AFTER '. 
77 MSGEOF PIC X(37> 

VALUE ' **ERROR UNEXPECTED EOF READING AFTER '. 
77 MSGNEF PIC X<23) VALUE ' **ERROR EOF NOT FOUND**' 
01 REC1. 



02 
03 
03 
02 
66 



REC-ID. 
REC-HD 
REC- HO 
FILLER 



PIC X(4) VALUE 'RECD*. 
PIC S9(4> VALUE ZERO. 
PIC A(75) VALUE SPACES. 
RECID RENAMES REC-ID. 
01 VER-REC. 

02 VER-ID. 

03 VER-HD PIC X(4) VALUE 'RECD*. 
03 VER-NO PIC S9(4) VALUE ZERO. 

PROCEDURE DIVISION. 
BASE-SECTION SECTION 0. 

DISPLAY ' START TEST SEG-S AMPLE' . 

OPEN OUTPUT FILE-1. 

PERFORM W-80-0 THRU W-80-9. 

PERFORM W-30-0 THRU W-30-9. 

PERFORM W-60-0 THRU W-60-9. 

PERFORM W-40-0 THRU W-40-9. 
BASE- 50. 

CLOSE FILE-1. 

OPEN INPUT FILE-1. 

PERFORM R-80-0 THRU R-80-9. 

GO TO R-60-0. 
BASE-60. 

PERFORM R-40-0 THRU R-40-9. 

R2AD FILE-1 INTO R3C1 AT END GO TO BASE-70. 

DISPLAY MSGHDR DISPLAY MSGNEF 

MOVE ' E' TO ERRORSW. 
BASE-70. 

CLOSE FILE-1. 
BASE-90. 

IF ERRORSW IS EQUAL TO ' E* 

DISPLAY 'END TEST SEG-SAMPLE UNSUCCESSFUL RUN' ELSE 

DISPLAY 'END TEST SEG-SAMPLE SUCCESSFUL RUN". 

STOP RUN. 
SECTION-20 SECTION 20. 
W-20-0. 

DISPLAY 'SECTION 20 WRITE'. 

NOTE ENTERED BY PERFORM FROM W-80-0. 

PERFORM W-21-0 THRU W-21-9 5 TIMES. 
W-20-9. 

EXIT. 
W-21-0. 

WRITE RECFD1 FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE ' E' TO ERRORSW 

GO TO BASE-50. 

ADD 0001 TO REC-NO. 
W-21-9. 

EXIT. 
R-20-0. 



00155370 
00155380 
00155390 
00155400 
00155410 
00155420 
00155430 
00155440 
00155450 
00155460 
00155470 
00155480 
00155490 
00155500 
00155510 
00155520 
00155530 

00155550 
00155560 
00155570 
00155580 
00155590 
00155600 
00155610 
00155620 
00155630 
00155640 
00155650 
00155660 
00155670 
00155680 
00155690 
00155700 
00155710 
00155720 
00155730 



00155760 
00155770 
00155780 
00155790 
00155800 
00155810 
00155820 
00155830 
00155840 
00155850 
00155860 
00155870 
00155880 
00155890 
00155900 
00155910 
00155920 
00155930 



Figure 108. Sample Segmentation Program (Part 2 of 14) 
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00115 


001220 


00116 


001230 


00117 


001240 


00118 


001250 


00119 


001260 


00120 


001270 


00121 


001280 


00122 


001290 


00123 


001300 


00124 


001310 


00125 


001320 


00126 


001330 


00127 


001340 


00128 


001350 


00129 


001360 


00130 


001370 


00131 


001380 


00132 


001390 


00133 


001400 


00134 


001410 


00135 


001420 


00136 


001430 


00137 


001440 


00138 


001450 


00139 


001460 


00140 


001470 


00141 


001480 


00142 


001490 


00143 


001500 


00144 


001510 


00145 


001520 


00146 


001530 


00147 


001540 


00148 


001550 


00149 


001560 


00150 


001570 


00151 


001580 


00152 


001590 


00153 


001600 


00154 


001610 


00155 


001620 


00156 


001630 


00157 


001640 


00153 


001650 


00159 


001660 


00160 


001670 


00161 


001680 


00162 


001690 


00163 


001700 


00164 


001710 


00165 


001720 


00166 


001730 


00167 


001740 


00168 


001750 


00169 


001760 


00170 


001770 


00171 


001780 



DISPLAY 'SECTION 20 READ'. 

NOTE ENTERED BY PERFORM FROM 3ASE-4 0. 

PERFORM R-21-0 THRU R-21-9 5 TIMES. 
R-20-9. 

EXIT. 
R-21-0. 

READ FILE-1 INTO RECl AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE ' E' TO ERRORSW 

GO TO R-21-9. 

IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGhDR DISPLAY 'EXPECTED ' VER-ID 

ADD 1 TO ERCTFL MOVE ' E" TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 
R-21-9. 

IF ERCTFL IS GREATER THAN 3 

GO TO BASE-70. 
SECTION-30 SECTION 30. 
W-30-0. 

DISPLAY 'SECTION 30 WRITE'. 

NOTE ENTERED BY PERFORM FROM BASE-SECTION. 

PERFORM W-31-0 THRU W-31-9 11 TIMES. 
W-30-9. 

EXIT. 
W-31-0. 

WRITE RECFDl FROM RECl INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE ' E' TO ERRORSW 

GO TO BASE-50. 

ADD 0001 TO REC-NO. 
W-31-9. 

EXIT. 
R-30-0. 

DISPLAY "SECTION 30 READ'. 

NOTE ENTERED BY GO TO FROM R-60-0. 

PERFORM R-31-0 THRU R-31-9 11 TIMES. 

GO TO BASE-60. 
R-31-0. 

READ FILE-1 INTO RECl AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE ' E' TO ERRORSW 

GO TO R-31-9. 

IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGHDR DISPLAY 'EXPECTED ' VER-ID 

ADD 1 TO ERCTFL MOVE 'E' TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 
R-31-9. 

IF ERCTFL IS GREATER THAN 3 

GO TO BASE-70, 
SECTION-40 SECTION 40. 
W-40-0. 

DISPLAY 'SECTION 40 WRITE'. 

NOTE ENTERED BY PERFORM FROM BASE-SECTION. 

PERFORM W-41-0 THRU W-41-9 17 TIMES. 



00155940 
00155950 
00155960 
00155970 
00155980 
00155990 
00156000 
00156G10 
00156020 
00156030 
00156040 
00156050 
00156060 
00156070 
00156080 
00156090 
00156100 
00156110 
00156120 
00156130 
00156140 
00156150 
00156160 
00156170 
00156180 
00156190 
00156200 
00156210 
00156220 
00156230 
00156240 
00156250 
00156260 
0015b270 
0015&2S0 
00156290 
00156300 
00156310 
00156320 
00156330 
00156340 
0.0156 3.50- 
0015b360 
00156370 
00156380 
00156390 
00156400 
00156410 
00156420 
00156430 
00156440 
00156450 
00156460 
00156470 
00156480 
00156490 
00156500 



Figure 108. Sample Segmentation Program (Part 3 of 14) 
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00172 


001790 


00173 


001800 


00174 


001810 


00175 


001820 


00176 


001830 


00177 


001840 


00178 


001850 




rtftl O C f\ 






00180 


001870 


00181 


001880 


00182 


001890 


00183 


001900 


00184 


001910 


00185 


001920 


00186 


001930 


00187 


001940 


00188 


001950 


00189 


001960 


00190 


001970 


00191 


001980 


00192 


001990 


00193 


002000 


00194 


002010 


00195 


002020 


00196 


002030 


00197 


002040 


00198 


002050 


00199 


002060 


00200 


002070 


00201 


002080 


00202 


002090 


00203 


002100 


00204 


002110 


00205 


002120 


00206 


002130 


00207 


002140 


00208 


002150 


00209 


002160 


00210 


002170 


00211 


002180 


00212 


002190 


00213 


002200 


00214 


002210 


00215 


002220 


00216 


002230 


00217 


002240 


00218 


002250 


00219 


002260 


00220 


002270 


00221 


002280 


00222 


002290 


00223 


002300 


00224 


002310 


00225 


002320 


00226 


002330 


00227 


002340 


00228 


002350 



W-40-9. 

EXIT. 
W-41-0. 

WRITE RECFD1 FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE • E" TO ERRORSW 

GO TO EASE— 50. 

ADD 0001 TO REC-NO. 
W-41-9. 

EXIT. 
R-40-0. 

DISPLAY 'SECTION 40 READ". 

NOTE ENTERED BY PERFORM FROM BASE-60. 

PERFORM R-41-0 THRU R-41-0 7 TIMES. 

PERFORM R-20-0 THRU R-20-9. 
R-40-9. 

EXIT. 
R-41-0. 

READ FILE-1 INTO REC1 AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE ' E* TO ERRORSW 

GO TO R-41-9. 

IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGHDR DISPLAY 'EXPECTED ' VER-ID ' 

ADD 1 TO ERCTFL MOVE ' E* TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 
R-41-9. 

IF ERCTFL IS GREATER THAN 3 

GO TO BASE-70. 
SECTION-60 SECTION 60. 
W-60-0. 

DISPLAY 'SECTION 6 WRITE'. 

NOTE ENTERED BY PERFORM FROM BASE-SECTION. 

PERFORM W-61-0 THRU H-61-9 13 TIMES. 
W-60-9. 

EXIT. 
W-61-0. 

WRITE RECFD1 FROM RECl INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE ' E" TO ERRORSW 

GO TO BASE-50. 

ADD 0001 TO REC-NO. 
W-61-9. 

EXIT. 
R-60-0. 

DISPLAY 'SECTION 60 READ'. 

NOTE ENTERED BY GO TO FROM 3ASE-50. 

PERFORM R-61-0 THRU R-61-9 13 TIMES. 

GO TO R-30-0. 
R-61-0. 

READ FILE-1 INTO RECl AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE ' E' TO ERRORSW 

GO TO R-61-9. 



REC-ID 



00156510 
00156520 
00156530 
00156540 
00156550 
00156560 
00156570 
00156580 
00156590 
00156600 
00156610 
00156620 
00156630 
00156640 
00156650 
00156660 
00156670 
00156680 
00156690 
00156700 
00156710 
00156720 
00156730 
00156740 
00156750 
00156760 
00156770 
00156780 
00156790 
00156800 
00156810 
00156820 
00156830 
00156840 
00156850 
00156860 
00156870 
00156880 
00156890 
00156900 
00156910 
00156920 
00156930 
00156940 
00156950 
00156960 
00156970 
00156980 
00156990 
00157000 
00157010 
00157020 
00157030 
00157040 
00157050 
00157060 
00157070 



Figure 108. Sample Segmentation Program (Part 4 of 14) 
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00229 


002360 


00230 


002370 


00231 


002380 


00232 


002390 


00233 


002400 


00234 


002410 


00235 


002420 


00236 


002430 


00237 


002440 


00238 


002450 


00239 


002460 


00240 


002470 


00241 


002480 


00242 


002490 


00243 


002500 


00244 


002510 


0024 5 


002520 


00246 


002530 


0C247 


002540 


00248 


002550 


00249 


002560 


00250 


002570 


00251 


002580 


00252 


002590 


00253 


002600 


00254 


002610 


00255 


002620 


00256 


002630 


00257 


002640 


00258 


002650 


00259 


002660 


00260 


002670 


00261 


002680 


00262 


002690 


00263 


002700 


00264 


002710 


00265 


002720 


00266 


002730 


00267 


002740 


00268 


002750 


00269 


002760 


00-270- 


-&&277Q 


00271 


002780 


00272 


002790 


00273 


002800 


00274 


002810 



IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGHDR DISPLAY 'EXPECTED ' VER-ID 

ADD 1 TO ERCTFL MOVE 'E' TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 
R-61-9. 

IF ERCTFL IS GREATER THAN 3 

GO TO BASE-70. 
SECTION-80 SECTION 80. 
W-80-0. 

DISPLAY 'SECTION 80 WRITE*. 

NOTE ENTERED BY PERFORM FROM BASE-SECTION. 

PERFORM W-81-0 THRU W-81-9 7 TIMES. 

PERFORM W-20-0 THRU W-20-9. 
W-80-9. 

EXIT. 
w-81-0 = 

WRITE RECFD1 FROM REC1 INVALID KEY 

DISPLAY MSGHDR 

DISPLAY MSGEOX RECID 

MOVE 'E« TO ERRORSW 

GO TO BASE-50. 

ADD 0001 TO REC-NO. 
W-81-9. 

EXIT. 
R-80-0. 

DISPLAY 'SECTION 80 READ'. 

NOTE ENTERED BY PERFORM FROM BASE-50. 

PERFORM R-81-0 THRU R-81-9 17 TIMES. 
R-80-9. 

EXIT. 
R-81-0. 

READ FILE-1 INTO REC1 AT END 

DISPLAY MSGHDR DISPLAY MSGEOF 

ADD 4 TO ERCTFL MOVE 'E* TO ERRORSW 

GO TO R-81-9. 

IF REC-ID IS NOT EQUAL TO VER-ID 

DISPLAY MSGHDR DISPLAY 'EXPECTED ' VER-ID 

ADD 1 TO ERCTFL MOVE 'E' TO ERRORSW 

MOVE REC-ID TO VER-ID. 

ADD 1 TO VER-NO. 

R-ai^a,. 

IF ERCTFL IS GREATER THAN 3 
GO TO BASE-70. 
R-81-9. 

EXIT. 



00157080 
00157090 
00157100 
00157110 
00157120 
00157130 
00157140 
00157150 
00157160 
00157170 
00157180 
00157190 
00157200 
00157210 
00157220 
00157230 
00157240 
00157250 
00157260 
00157270 
00157280 
00157290 
00157300 
00157310 
00157320 
00157330 
00157340 
00157350 
00157360 
00157370 
00157380 
00157390 
00157400 
00157410 
00157420 
00157430 
00157440 
00157450 
00157460 
00157470 
00157480 

00i57"5~00 
00157510 



INTRNL NAME 

DNM=2-234 

DNM=2-253 

DNM=2-272 

DNM=2-292 

DNM=2-308 

DNM= 2-324 

DNM=2-340 

DNM=2-356 

DNM=2-372 

DNM=2-389 

DNM=2-408 

DNM=2-424 

DNM= 2-440 

DNM=2-451 

DNM=2-469 

DNM=2-489 

ONM=3-000 

DNM=3-016 



LVL 

FD 

01 

77 

77 

77 

77 

77 

77 

01 

02 

03 

03 

02 

66 

01 

02 

03 

03 



SOURCE NAME 

FILE-1 

RECFD1 

ERRORSW 

ERCTFL 

MSGHDR 

MSGEOX 

MSGEOF 

MSGNEF 

REC1 

REC- ID 

REC-HD 

REC-NO 

FILLER 

RECID 

VER-REC 

VER- ID 

VER-HD 

VER-NO 



BASE 
DCB=01 
EL=1 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 
BL=2 



DISPL 

000 
000 
001 
003 
019 
03D 
062 
080 
080 
080 
084 
088 
080 
0D8 
0D8 
0D8 

nnp 



INTRNL NAME 

DNM=2-234 

DNM=2-253 

DNM=2-272 

DNM=2-292 

DNM=2-308 

DNM=2-324 

DNM=2-340 

DNM=2-356 

DNM=2-372 

DNM=2-389 

DNM=2-408 

DNM=2-424 

DNM=2-440 

DNM=2-451 

DNM=2-469 

DNM=2-489 

DNM=3-000 



DEFINITION 

DS 83C 
DS 1C 
DS 2C 
DS 22C 
DS 36C 
DS 37C 
DS 23C 
DS 0CL83 
DS 0CL8 
DS 4C 
DS 4C 
DS 75C 
DS 0CL8 
DS 0CL8 
DS 0CL8 
DS 4C 
DS 4C 



US^GE 

OS AM 

DISP 

DI3P 

DISP-NM 

DISP 

DISP 

DISP 

DISP 

GROUP 

GROUP 

DISP 

DI3P-NM 

DISP 

GROUP 

GROUP 

GROUP 

DISP 

DI3P-NM 



Figure 108. Sample Segmentation Program (Part 5 of 14) 
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MEMORY MAP 

TGT 00218 

SAVE AREA 00218 

SWITCH 00260 

TALLY 00264 

SORT SAVE 00268 

ENTRY-SAVE 0026C 

SORT CORE SIZE 00270 

RET CODE 00274 

SORT RET 00276 

WORKING CELLS 00278 

SORT FILE SIZE 003A8 

SORT MODE SIZE 003AC 

P3T-VN TBL 003B0 

TGT-VN TBL 003B4 

VCONPTR 00 3B8 

LENGTH OF VN TBL 003BC 

LABEL RET 00 3BE 

CURRENT PRIORITY 00 3BF 

DBG R14SAVE 003C0 

COBOL INDICATOR 003C4 

A(INITl) 003C8 

DEBUG TABLE PTR 003CC 

SUBCOM PTR 00 3D0 

SORT DDNAME 003D4 

UNUSED 00 3DC 

DBG R11SAVE 003F0 

UNUSED 00 3F4 

PRBLl CELL PIR 003F8 

GENCBTBL PTR 003FC 

UNUSED 00100 

TA LENGTH 00401 

UNUSED 00404 

OVERFLOW CELLS 0040C 

BL CELLS 0040C 

DECBADR CELLS 00 414 

TEMP STORAGE 00418 

TEMP STORAGE- 2 00 4 20 

TEMP STORAGE-3 00420 

TEMP STORAGt-4 00420 

BLL CELLS 00420 

VLC CELLS 00 428 

SBL CELLS 00428 

INDEX CELLS 00428 

SUBADR CELLS 00428 

ONCTL CELLS 00428 

PFMCTL CELLS 004 28 

PFMSAV CELLS 00 4 50 

VN CELLS 00498 

SAVE AREA =2 00 4E0 

SAVE AREA =3 004E0 

XSASW CELLS 004F8 

XSA CELLS 004E8 

Figure 108. Sample Segmentation Program (Part 6 of 14) 
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LITERAL POOL (HEX) 

005C8 (L1T+0) 1C4C3C00 4805EF48 00000005 000E0011 0007000D 
DISPLAY LITERALS (BCD) 



005DC (LTL+20) 

00614 (LTL+76) 

0064C (LTL+132) 

00684 (LrL+188) 

006BC (LTL+244) 



' START TEST SEG-SAMPLEEND TEST SE3-SAMPLE UNSUCCESSFUL RU* 
' NEND TEST SE3-SAMPLE SUCCESSFUL RUNSECTION 20 WRITESECTI' 
' ON 20 READEXPECTED FOUND SECTION 30 WRITESECTION 30 REA 8 
'DSECTION 40 WRITESECTION 40 READSECTION 60 WRITESECTION • 
' 60 READSECTION 80 WRITESECTION 80 READ' 



PGT 

DEBUG LINKAGE AREA 
OVERFLOW CELLS 
VIRTUAL CELLS 
VIRTUAL EBCDIC NAMES 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
DC3 ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERALS 
PROCEDURE BLOCK CELLS 



00510 

00510 
00510 
00514 
00528 
00550 
00550 
0057C 
00580 
005C8 
005DC 
006E4 



REGISTER ASSIGNMENT 



REG 6 
REG 7 



BL =2 
BL =1 



WORKING-STORAGE STARTS AT LOCATIGN 00088 FOR A LENGTH OF 000E0. 

Figure 108. Sample Segmentation Program (Part 7 of 14) 



Using the Segmentation Feature 319 



***********±***SEGMENT OF PTY 30************ J 



133 


VERB 


65 


000000 












?W= 


= 016 


EQU 


* 






134 


VERB 


66 


000000 












PN= 


= 017 


EQU 


* 






135 


VFRR 


67 
































000000 


58 


FO 


C 


004 








L 


15, 004(0, 12) 


V(ILBODSPO) 










000004 


05 


IF 












BALR 


1,15 












000006 


0001 












DC 


X'0001' 












000008 


10 














DC 


X*10' 












000009 


000010 










DC 


X'OGOOIG 1 












oooooc 


0C000156 








DC 


X' 0C000156' 


LIT+158 










000010 


0000 












DC 


X'0000' 












000012 


FFFF 












DC 


X'FFFF' 






137 


VERB 


68 
































000014 


D2 


03 


D 


258 D 


294 






MVC 


258(4,13) ,294(13) 


PSV=9 


VS=06 








00001A 


41 


00 


B 


02A 








LA 


0,02A(0,11) 


Grt=019 










00001E 


50 


00 


D 


294 








ST 


0,294(0,13) 


VN=06 










000022 


48 


10 


c 


0C4 








LH 


1, 0C4(0, 12) 


LIT+12 










000026 


50 


10 


D 


218 








ST 


1,218(0,13) 


PFM=3 










00002A 












GN= 


= 019 


EQU 


* 












00002A 


38 


EO 


D 


218 








L 


14,218(0,13) 


PFM=3 










00002E 


06 


EO 












BCTR 


14,0 












000030 


50 


EO 


D 


218 








ST 


14, 218(0, 13) 


PFM=3 










000034 


12 


EE 












LTR 


14,14 












000036 


58 


BO 


C 


IDG 








L 


11,1D8(0, 12) 


PBL=2 










00003A 


47 


40 


B 


048 








BC 


4,048(0,11) 


GN=054 










00003E 


58 


FO 


C 


OOC 








L 


15, OOC(0, 12) 


V(ILBOSGMl) 










000042 


05 


EF 












BALR 


14,15 












000044 


IE 














DC 


X«1E' 












000045 


02 














DC 


X* 02' 












000046 


005A 












DC 


X'005R' 


PN=019 










000048 












GN= 


= 054 


EQU 


* 












000048 


D2 


03 


D 


294 D 


258 






MVC 


294(4, 13), 258(13) 


VN=06 


PSV=9 


138 


VERB 


69 


00004E 












PN= 


= 018 


equ 


* 






139 


VERB 


70 


























140 


VERB 


71 
































00004E 


58 


00 


D 


290 








L 


0,290(0,13) 


VN=05 










000052 


58 


FO 


C 


014 








L 


15, 014(0, 12) 


V(ILBOSGMO) 










000056 


05 


EF 












BALR 


14,15 












000058 


1E00 












DC 


X'lEOO" 












00005A 












PN= 


= 019 


EQU 


* 






141 


VERB 


72 
































00005A 


D2 


52 


7 


000 6 


080 






MVC 


000(83,7) ,080 (b) 


DNM=2-253 


DNM=2-372 








000060 


58 


10 


C 


06C 








L 


1, 06C(0, 12) 


DCB=1 










000064 


18 


21 












LR 


2,1 












000066 


58 


40 


2 


024 








L 


4,024(0, 2) 












00006A 


D2 


02 


4 


019 C 


04D 






MVC 


019(3,4) ,04D(12) 




GN=020+1 








000070 


58 


10 


C 


06C 








L 


1,06C(0,12) 


DCB=1 










000074 


58 


00 


1 


04C 








L 


0,04C(0,1) 












000078 


58 


FO 


1 


030 








L 


15,030(0,1) 












00007C 


44 


00 


1 


060 








EX 


0, 060(0, 1) 












000080 


50 


10 


D 


1F4 








ST 


1,1F4<0,13) 


BL =1 










000084 


58 


70 


D 


1F4 








L 


7,114(0,13) 


BL =1 





Figure 108. Sample Segmentation Program (Part 8 of 14) 
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142 



143 



144 
145 



146 



147 



148 
149 



150 







000088 


96 01 4 01B 






00008C 


47 FO B OCE 






000090 




VERE 


73 










000090 


58 FO C 0C4 






000094 


05 IF 






000096 


0001 






000098 


00 






000099 


000016 






00009C 


0D0001F8 






0000A0 


0003 






0000A2 


FFFF 


VERB 


74 










0000A4 


58 FO C 004 






0000A8 


05 IF 






0000AA 


0001 






00 00AC 


00 






0000AD 


000024 






000OB0 


OD0001F8 






0C00B4 


0019 






0000B6 


00 






0000B7 


000008 






00003A 


0D0001F8 






OOOOBE 


0080 






OOOOCO 


FFFF 


VERB 


75 










0000C2 


92 C5 6 000 


VERB 


76 







VERB 77 



152 



VERB 


79 






VERB 


80 










OOOOEO 


58 00 D 294 






0000E4 


58 FO C 014 






. 0.0.0QE8 


. 0.5....EF. 






0000EA 


1E00 






OOOOEC 




VERB 


81 










0000EC 


58 FO C 004 






OOOOFO 


05 IF 






0000F2 


0001 






0000F4 


10 






0000F5 


OOOOOF 






0000F8 


0C000166 






OOOOFC 


n(\nn 






OOOOFE 


FFFF 


VERB 


82 









OI 


01B(4),X'01* 




BC 


15,0CE(0,11) 


GN=020 


EQU 


* 




L 


15, 004(0, 12) 




EALR 


1.15 




DC 


X'0001' 




DC 


X' 00" 




DC 


X'000016' 




DC 


X' 0D0001F8' 




DC 


X'0003' 




DC 


X' FFFF* 




L. 


15,004(0,12) 




BALR 


1, 15 




DC 


X' 0001' 




DC 


X'OO' 




DC 


X' 000024' 




DC 


>;*0D0001F-8' 




DC 


X'0019' 




DC 


X'OO" 




DC 


X* 000008* 




DC 


X' 0D0001F8' 




DC 


X* 0080* 




DC 


X'FFFF' 



0000C6 58 BO C 1D4 

0000CA 47 FO B ODE 
0000CE 

0O0OCE F2 73 D 200 6 084 

0000D4 FA 20 205 C CB8 

0000DA F3 32 6 084 D 205 

OOOOEO 



GN-021 



PN=021 



GN=0 21 



V(ILBODSPO) 



BL =2 



VlILBODSPO) 



fcVI 000(6), X'C5* 



L 

BC 
EQU 

PACK 

AP 

UNPK 

FQU 



L 

L 

BALR. 

DC 

EQU 

L 

BALR 

DC 

DC 

DC 

DC 

DC 

DC 



11, 1D4<0, 12) 
15, 0DE(0,11) 



200(8, 13), 084(4, 6) 
205(3,13) ,0B8<1, 12) 
084(4, 6), 205(3, 13) 



0,294(0,13) 
15, 014(0, 12) 
14,15 

x' is6 6' 



15,004(0,12) 

1,15 

X' 0001' 

X'10' 

X' 00000F' 

X' 0C000166' 

X' 0000' 

X'FFFF' 



000100 D2 03 D 25C D 291 
000106 41 00 B 116 
00010A 50 00 D 298 



MVC 25C(4, 13), 298(13) 
LA 0,116(0,11) 
ST 0,298(0,13) 



DNM=2-272 



PBL=1 
FN=0 3 



TS=C1 
TS=06 
DNM=2-424 



VlM=06 
V(ILBOSGMO) 



V(ILBODSPO) 



LIT+174 



PSV=10 
GN=0 22 
VN=07 



DNM=2-424 
LIT + 
TS=06 



VN=07 



Figure 108. Sample Segmentation Program (Part 9 of 14) 



Using the Segmentation leature 321 



24 



153 

154 
155 



VERB 8 3 



VERB 84 



VERB 85 



86 



156 



VERB 87 



157 



15^ 

158 



VERB 8 8 



VER3 8 9 



VER3 90 



00010E 


48 


10 


C 


0C4 




LH 


1, 0C4(0, 12) 


LIT+12 




000112 


50 


10 


D 


21C 




ST 


1,21C<0,13) 


PFM=4 




000116 










GN=022 


EQU 


* 






000116 


58 


EO 


D 


21C 




L 


14.21CC0.13) 


PFM=4 




00011A 


06 


EO 








BCTR 


14. 






00011C 


50 


EO 


D 


21C 




ST 


14,21C(0,13> 


PFM=4 




000120 


12 


EE 








LTR 


14. 14 






000122 


47 


40 


B 


130 




BC 


4,130(0,11) 


GN=055 




000126 


58 


FO 


C 


ooc 




L 


15, 00CC0, 12) 


V(ILBOSGMl) 




00012A 


05 


EF 








BALR 


14,15 






00012C 


IE 










DC 


X'lE" 






00012D 


02 










DC 


X' 02' 






00012E 


013E 








DC 


X'013E' 


PN=022 




000130 










GN=055 


EQU 


* 






000130 


D2 


03 


D 


298 D 


25C 


MVC 


298(4,13), 25C(13) 


VN=07 


PSV=10 


000136 


58 


BO 


C 


1D4 




L 


11, 1D4(C, 12) 


PBL=1 




00013A 


47 


FO 


Li 


182 




EC 


15,182(0,11) 


PN=04 




00013E 










PN=022 


EQU 


* 






00013E 


58 


10 


c 


06C 




L 


1,06C<0,12) 


DCB=1 




000142 


18 


21 








LR 


2,1 






000144 


D2 


02 


2 


021 C 


051 


MVC 


021(3, 2), 051(12) 




GN=023+1 


00014A 


58 


FO 


1 


030 




L 


15, 030(0, 1) 






00014E 


05 


EF 








BALR 


14,15 






000150 


50 


10 


D 


1F4 




ST 


1, 1F4(0, 13) 


BL =1 




000154 


58 


70 


D 


1F4 




L 


7,1F4(0,13) 


BL =1 




000158 


02 


52 


6 


080 7 


000 


MVC 


080(83,6), 000(7) 


DNM=2-372 


DNM=2-253 


00015E 


47 


FO 


B 


1A8 




BC 


15,1A8(0,11) 


GlM=024 




000162 










GN=023 


EQU 


* 






000162 


58 


FO 


C 


004 




L 


15, 004(0, 12) 


V(ILBODSPO) 




000166 


05 


IF 








BALR 


1,15 






000168 


0001 








DC 


X'OOOl" 






00016A 


00 










DC 


X" 00* 






00016B 


000016 






DC 


X'000016' 






00016E 


0D0001F8 




DC 


X' 0D0001F8' 


BL =2 




000172 


0003 








DC 


X'0003' 






000174 


FFFF 








DC 


X» FFFF' 






000176 


58 


FO 


C 


004 




L 


15,004(0,12) 


V(ILBODSPO) 




00017A 


05 


IF 








BALR 


1, 15 






00017C 


0001 








DC 


X'COOl' 






00017E 


00 










DC 


X'OO' 






00017F 


00002: 


5 






DC 


X' 000025 1 






000182 


ODOOOlFf 






DC 


X'0D0001F8' 


BL =2 




000186 


003O 








DC 


X' 003D' 






000188 


FFFF 








DC 


X'FFFF' 






00018A 


F2 


71 


D 


200 6 


001 


PACK 


200(8, 13), 001(2, 6) 


TS=01 


DNK=2-292 


000190 


FA 


10 


D 


206 C 


0B9 


AP 


206(2,13),0B9(1,12) 


TS=07 


LIT+1 


00 0196 


F3 


11 


6 


01 D 


206 


UNPK 


001(2, 6), 206(2, 13) 


DNM=2-292 


TS=07 


00019C 


92 


C5 


6 


000 




MVI 


000(6), X'C5' 


DNM=2-272 




0001A0 


58 


BO 


C 


1D8 




L 


11, 1D8(0, 12) 


PEL=2 





Figure 108. Sample Segmentation Program (Part 10 of 14) 



322 



0001A4 
0001A8 



47 FO B 226 



159 



160 



VERB 91 



VERB 92 



160 



VERB 93 



161 

161 
162 

163 

164 
165 

166 



VERB 94 

VERB 95 

VERB 96 

VERB 97 

VERB 98 

VERB 99 

VERB 100 



0001A8 D5 07 6 080 6 0D8 
0001AE 47 80 B 214 



0001B2 
0001B6 
0001B8 
0001BA 
0001BB 
0001BE 
0001C2 
0001C4 

0001C6 
0001CA 
0001CC 
0001CE 
0001CF 
O001D2 
0001D6 
0001D8 
0001D9 
0001DC 
0001E0 
0001E2 
0001E3 
0001E6 
0001EA 
0001EC 
0001ED 
0001F0 
0001F4 
0001F6 

0001F8 
0001FE 
000204 



58 FO C 004 

05 IF 

0001 

00 

000016 

OD0001F8 

0003 

FFFF 

58 FO C 004 

05 IF 

0001 

10 

000009 

0C000146 

0000 

00 

000008 

0D0001F8 

00D8 

10 

000007 

0C00014F 

0000 

00 

000008 

0D0001F8 

0080 

FFFF 

F2 71 D 200 6 001 
FA 10 D 206 C 0B8 
F3 11 6 001 D 206 



00020A 92 C5 6 000 

00020E" D2 67 6 0D8 6 80 
000214 

000214 F2 73 D 200 6 ODC 

00021A FA 20 D 205 C 0B8 

000220 F3 32 6 ODC D 205 

000226 

000226 F2 71 D 200 6 001 

00022C F9 10 D 206 C OBA 

000232 47 DO B 23E 



BC 


15, 226(0, 11) 




PN=023 






GN=024 EQU 


* 










CLC 


080(8,6) ,0D8(6) 




DNM=2-389 


DNM=2- 


489 


BC 


8,214(0,11) 




GN=025 






L 


15, 004(0, 12) 




V(ILBODSPO) 






BALR 


1,15 










DC 


X'0001' 










DC 


X'OO' 










DC 


X'000016' 










DC 


X'0D0001F8' 




BL =2 






DC 


X'0003' 










DC 


X'FFFF* 










L 


15,00410,12) 




VULBODSPO) 






BALR 


1,15 










DC 


X" 0001* 










DC 


X'10' 










DC 


X' 000009' 










DC 


X'0C000146* 




LIT+142 






DC 


X' 0000 s 










DC 


X'OO* 










DC 


X' 000008' 










DC- 


X'ODOOOIFS' 




BL =2 






DC 


X" 00D8' 










DC 


X'10' 










DC 


X' 000007' 










DC 


X'0C00014F' 




LIT+lbl 






DC 


X« 0000' 










DC 


X'OO' 










DC 


X' 000008' 










DC 


X'OD0001F8' 




BL =2 






DC 


X'OOSO' 










DC 


X'FFFF* 










PACK 


200(8, 13), 001(2, 


,6) 


TS=01 


DNh=2- 


-292 


AP 


206(2,13) ,0B8 (1, 


, 12) 


TS=07 


LII' + O 




UNPK 


001(2, 6), 206(2,! 


L3) 


DNM=2-292 


TS=07 




KVI 


000(6), X'C5' 




DNM=2-272 






MVC 


0D8T8, 6), 080(6) 




"DNM=2-CFS~9" 


DNR-2- 


-389 


GN=025 EQU 


* 










PACK 


200(8,13) ,0DC(4, 


,6) 


TS=01 


DNM=3- 


•lb 


AP 


205(3, 13), 0B?(1, 


,12) 


TS=06 


LI1+0 




UNPK 


0DC(4,6) , 205(3,: 


L3) 


DNM=3-16 


To = 06 





PN=023 EQU * 

PACK 200(8, 13), 001(2, 6) 

CP 206(2, 13), OBAd, 12) 

BC 13,23E(0,11) 



000236 
00023A 



58 BO C 1D4 
47 FO B 200 



L 

BC 



ll,lD4(0 r 12) 
15, 200(0, 11) 



TS=01 


DMM=2-292 


TS=07 


L1T + 2 


GN=0 26 




PBL=1 




PN=05 





26 



00023E 






GN=026 EQU 


* 




00023E 


58 00 D 


298 


L 


0,298(0,13) 


VN=07 


000242 


58 FO C 


014 


L 


15, 014(0, 12) 


V(ILBOSGKO) 


000246 


05 EF 




BALR 


14,15 




000248 


1E00 




DC 


X'lEOO' 




00024A 


58 FO C 


00C 


L 


15,00C(0,12) 


V(ILBOEGMl) 


00024E 


(It cc 




BALR 


14, 15 




000250 


28 




DC 


X*28* 




000251 


03 




DC 


X'03' 




000252 


0000 




DC 


X'0000' 


PN=0 24 



Figure 108. Sample Segmentation Program (Part 11 of 14) 



Using the Segmentation reature 32 3 



CRORS-RFFERFNC^. mTTTONARY 



REFERENCE 



0000t>7 

000056 000123 000127 000131 000157 000161 000165 000193 000197 000201 000227 
000231 000235 000263 000267 000271 

000055 000090 000094 000109 000123 000127 000144 000157 000161 000178 000193 

000197 000214 000227 000231 000249 000263 000267 

000046 000076 000082 000083 000088 000092 000106 000121 000141 000155 000175 

000191 000211 000225 000246 000261 

000060 000122 000156 000192 000226 000262 

000058 000108 000143 000177 000213 000248 

000057 000089 000107 000122 000126 000142 000156 000160 000176 000192 000196 
000212 000226 000230 000247 0002o2 000266 

000062 000089 
000065 

000064 000125 000126 000128 000159 000160 000162 000195 000196 000198 000229 

000230 000232 000265 000266 000268 

000066 000111 000146 00018C 000216 000251 

000053 000088 000106 000121 000141 000155 000175 000191 000211 000225 000246 

000261 

000068 000108 000143 000177 000213 000248 

000063 000088 000106 00C121 000141 000155 000175 000191 000211 000225 000246 
000261 

000071 

000070 000125 000126 000128 000159 000160 000162 000195 000196 000198 000229 

000230 000232 000265 00026b 000268 

000072 000129 000163 000199 000233 000269 
000069 

Figure 108. Sample Segmentation Program (Part 12 of 14) 
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PROCEDURE NAMES 



DEFN 



REFERENCE 



EASE-SECTION 

BASE- 50 

EASE-60 

BASE- 70 

BASE-90 

R-20-0 

R-20-9 

R-21-0 

R-21-9 

R-30-0 

R-31-0 

R-31-9 

R-40-0 

R-41-0 

R-41-9 

R-60-0 

R-61-0 

R-61-9 

R-80-0 

R-80-9 

R-81-0 

R-81-8 

R-81-9 

SECTION- 20 

SECTION-30 

SECTION- 40 

SECTION-bO 

SECTION- 8 

W-20-0 

W-20-9 

W-21-0 

W-21-9 

W-30-0 

W-30-9 

W-31-0 

W-31-9 

W-40-0 

W-40-9 

W-41-0 

W-41-9 

W-60-0 

W-60-9 

W-61-0 

W-61-9 

W-80-0 

W-80-9 

W-81-0 

W-81-9 



000074 
000081 
000086 
000091 
000093 
000114 
000118 
000120 
000130 
000149 
000154 
000164 
000183 
000188 
000190 
000200 
000219 
000224 
000234 
000254 
000258 
000260 
000270 
000273 
000098 
000133 
000167 
000203 
000237 
000099 
000103 
000105 
000112 
000134 
000138 
000140 
000147 
000168 
GW17^- 
000174 
000181 
000204 
000208 
000210 
000217 
000238 
000243 
000245 
000252 



000110 000145 000179 000215 000250 

000153 

000088 000132 000166 000202 000236 000272 

000187 

000187 

000117 

000117 000124 

000223 

000152 

000152 000158 

000087 

000087 

000186 

000194 

000085 

000222 

000222 000228 

000084 

000084 

000257 

000257 000264 

000132 
000166 
000202 
000236 
000242 
000242 
000102 
000102 
000078 
000078 
000137 
000137 
000080 



000171 
000171 
000079 
000079 
000207 
000207 
000077 
000077 
000241 
000241 



Figure 108. Sample Segmentation Program (Part 13 of 14) 



Using the Segmentation Feature 325 



F88-LEVEL LINKAGE EDITOR OPTIONS SPKCTFTKn T.TST. OVLY 
DEFAULT OPTION(S) USED - SIZE=( 90112, 12288) 

IEW0000 INSERT SEGOSAMP 

IEW0000 OVERLAY A 

IEW0000 INSERT SEG0SA30 

IEW0000 OVERLAY A 

IEW0000 INSERT SEG0SA40 

IEW0000 OVERLAY A 

IEW0000 INSERT SEG0SA60 

IEW0000 OVERLAY A 

IEW00C0 INSERT SEG0SA80 

IEW0000 ENTRY SEGOSAMP 

****RUN DOES NOT EXIST BUT HAS BEEN ADDED TO DATA SET 

START TEST SEG-SAMPLE 

SECTION 80 WRITE 

SECTION 20 WRITE 

SECTION 30 WRITE 

SECTION 6 WRITE 

SECTION 40 WRITE 

SECTION 8 READ 

SECTION 60 READ 

SECTION 30 READ 

SECTION 4 READ 

SECTION 20 READ 

END TEST SEG-SAMPLE SUCCESSFUL RUN 

Figure 108. Sample Segmentation Program (Part 14 of 14) 
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USING THE CHECKPOINT/RESTART FEATURE 



The IBM Operating System Checkpoint/ 
Restart feature is designed to be used with 
programs running for an extended period of 
time when interruptions may halt processing 
before the end of the job. The feature is 
available with both seguential and priority 
scheduling systems. The feature may be 
used when the programmer anticipates anv 
type of interruption, i.e., interruptions 
caused by machine malfunctions, 
input/output errors, or intentional 
operator intervention, etc. It allows the 
interrupted program to be restarted at the 
job step or at a point other than at the 
beginning of the job step. The feature 
consists of two routines: Checkpoint and 
Restart. 

The Checkpoint rout ine is invoked from 
the COBOL load module containing the user's 
program. It moves information stored in 
registers and in main storage into a 
checkpoint record at user-designated points 
during execution of tne program. The 
programmer specifies these points using the 
COBOL RERUN clause in the Environment 
Division. 



indicates that a checkpoint record is to be 
written onto a checkpoint data set whenever 
a specified number of records on that file 
are processed or when end of volume is 
reached while processing a file. Ihe 
programmer decides when he wants the 
checkpoints taken as he codes the RERUN 
clause. The checkpoint records are written 
on the checkpoint data set defined by the 
DD statement and are referenced by 
system-name in the RERUN clause. The DD 
statement describes both a checkpoint data 
set and a checkpoint method. 

Checkpoint records on ASCII-collated 
sorts can be taken, but the system-name 
indicating the checkpoint data set must not 
specify an ASCII file. 



Note: If checkpoints are to be taken 
during a sorting operation, a DD statement 
called SORTCKPT must be added when the 
program is executed. 



The Restart ro utine restarts an 
interrupted program. Restart can occur at 
the beginning of a job step, or at a 
checkpoint if a checkpoint record has been 
written. The checkpoint record will 
contain all information necessary to 
restart the program. Restart can be 
initiated at any time after the program was 
interrupted; that is, it may be run 
immediately after the interrupt has 
occurred, as an automatic restart, or at a 
later time convenient to the programmer, as 
a deferred restart. 

The COBOL RERUN clause provides linkage 
to the system checkpoint routine. Hence, 
any cautions and restrictions on the use of 
the system Checkpoint/Restart feature also 
apply to the use of the RERUN clause. 

The Checkpoint/Restart feature is fully 
described in the publication I BM OS 
Supervisor Services. 



Checkpoint _Met hods 



The programmer may elect to store single 
or multiple checkpoints. 



Single: Only one checkpoint record exists 
at any given time. After the first 
checkpoint record is written, any 
succeeding checkpoint record overlays the 
previous one. This method is acceptable 
for most programs. It offers tne advantage 
of saving space on the checkpoint data set 
and allows the programmer to restart his 
program at the latest checkpoint. 

Multiple (multiple contiguous) : 
Checkpoints are recorded and numbered 
sequentially. Each checkpoint is saved. 
This method is used when the programmer may 
wish to restart a program at a checkpoint 
other than the latest one taken. 



TAKING A CHECKPOINT 



DD STATEMENT FORMATS 



In order to initiate a checkpoint, the 
programmer uses job control statements and 
the COBOL RERUN clause. The programmer 
associates each RERUN clause with a 
particular COBOL file. The RERUN clause 



The programmer records checkpoints on 
tape or direct access devices. Following 
are the DD formats to define checkpoint 
data sets. 
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For Tape: MOD 

r t 

| //ddname DD DSNAME=data-set-name, X| 

j// V0LUME=SER=VOlser, X| 

|// UNIT=deviceno, X| NEW 

| NEW J 

j// DISP=( , PASS), X| 

j MOD j 

|// DCB=(TRTCH=C),LABEL=(,NL) j PASS 

L J 



Note: The DCB parameter is necessary only 
for 7- track tape conversion; for 9-track 
tape it is not used. 



is specified for the multiple 
contiguous checkpoint method. 



is specified for the single checkpoint 
method. 



is specified in order to prevent 
deletion of the data set at the 
successful completion of the job step 
unless it is the last step in the job. 
If it is the last step, the data set 
will be deleted with PASS. 



KEEP 



For Mass Storage: 



| //ddname DD DSNAME=data- set-name, 

|// VOLUME=( PRIVATE, RETAIN, 

| // SER=volser), 

j // UNIT=deviceno, 

| // SPACE=(subparms) f 

| NEW 

|// DISP=( , PASS), KEEP, 

j MOD 

L 



— n 

X| 
X| 
X| 
X| 
XI 



is specified in order to keep the data 
set if the job step abnormally 
terminated and may be restarted. 



The following listings are examples that 
define checkpoint data sets. 



• To write single checkpoint records 
using tape: 



where : 



ddname 

is the same as the ddname portion of 
the system-name used in the COBOL 
RERUN clause to provide a link to the 
DD statement. 



//CHECKPT DD DSNAME=CHECKl, X 

// VOLUME=SER=ND00 3, X 

// UNIT=2400,DISP= (NEW, KEEP), X 

// LABEL=(,NL) 



ENVIRONMENT DIVISION. 



data-set-name 

is the name given to each particular 
data set used to write checkpoint 
records. This name identifies the 
% checkpoint data set to the Restart 
procedure (see "Restarting a 
Program") . 



volser 

identifies the volume by serial 
number. 



deviceno 

identifies the device. For tape it 
indicates the device number for 
7-track or 9-track tape. For mass 
storage, it indicates the device 
number for disk or drum. 



RERUN ON UT-2400-S-CHECKPT EVERY 
5000 RECORDS OF ACCT-FILE. 



• To write single checkpoint records 
using disk (note that more than one 
data set may share the same 
external-name) : 



//CHEK DD DSNAME=CHECK2, 

// VOLUME= ( PRIVATE, RETAIN, 

// SER=DB030, 

// UNIT=2314, DISP=(NEW f KEhP), 

// SPACE=(TRK, 300) 



ENVIRONMENT DIVISION. 



subparms 

specifies the amount of track space 
needed for the data set. 



RERUN ON UT-2314-S-ChEK EVERY 
20000 RECORDS OF PAYCODE. 
RERUN ON UT-231U-S-CHEK EVERY 
30000 RECORD OF IN-FILE. 
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• To write multiple contiguous checkpoint 
records (on tape) : 



tlHJOOUl jobname (ddname, unit, vols er> 
CflKPT checkid] 



//CHEKPT DD DSNAME=CHECK3 f X 

// V0LUME=SER=111111, X 

// UNIT=2400,DISP=(MOD,PASS) , X 

// LABEL=(,NL> 



ENVIRONMENT DIVISION. 



where checkid is the identification name of 
the checkpoint taken. Checkid is assigned 
by the control program as an 8-digit 
number. The first digit is the letter C, 
followed by a decimal number indicating the 
checkpoint. For example, checkid COOOOOOU 
indicates the fourth checkpoint taken in 
the job step. 



RERUN ON UT-2400-S-CHEKPT EVERY 
10000 RECORDS OF PAY-FILE. 



RESTARTING A PROGRAM 



Note ; A checkpoint data set must be 
sequential. 



DESIGNING A CHECKPOINT 



The programmer should design his 
checkpoints at critical points in his 
program so that data may be easily 
reconstructed. For example, in a program 
using mass storage files, changes to 
records in these files will replace 
previous information; thus the programmer 
should- be -sure he- can -identify- previousLy- 
processed records. Assume that a mass 
storage file contains loan records that 
periodically are updated for interest due. 
If a checkpoint is taken, records are 
updated, and then the program is 
interrupted, the records updated after the 
last cneckpoint will be updated a second 
time in error unless the programmer 
controls this condition. (He may set up a 
date field for each record and update the 
date each time the record is processed. 
Then, after the restart, by investigating 
the date field he can determine whether or 
not the record was previously processed. ) 
For efficient repositioning of a print 
file, the programmer should take 
checkpoints on that file only after 
printing the last line of a page. At 
system generation time, those ABEND codes 
for which the checkpoints are desired 
(DEFAULT) must be specified. 



MESSAGES GENERATED DURING CHECKPOINT 



The system checkpoint routine advises 
the operator of the status of the 
checkpoints taken by displaying informative 
messages on the console. 

When a checkpoint has been successfully 
completed, the following message will be 
displayed: 



The system Restart routine retrieves the 
information recorded in a checkpoint 
record, restores the contents of main 
storage and all registers. 

The Restart routine can be initiated in 
one of two ways : 

• Automatically at the time an 
interruption stopped the program 

• At a later time as a deferred restart 

The type of restart is determined by tne RD 
parame.t_er._of the __ job control language. 



RD Parameter 



The RD parameter may appear on either 
the JOB or the EXEC statement. If coded on 
the JOB statement, the parameter overrides 
any RD parameters on the EXEC statement. 
If the programmer wishes to have his 
program restart automatically, he codes 
RD=R or RD=RNC. RD=R indicates that 
restart is to occur at the latest 
checkpoint. The programmer should specify 
the RERUN clause for at least one data set 
in his program in order to record 
checkpoints. If no checkpoint is taken 
prior to interruption, restart occurs at 
the beginning of the job step. RD=RNC 
indicates that no checkpoint is to be 
written and any restart will occur at the 
beginning of the job step. In this case, 
RERUN clauses are unnecessary; if any are 
present, they are ignored. If the RD 
parameter is omitted, the CHKPT macro 
instruction remains activated, and 
checkpoints may be taken during processing. 
If an interrupt occurs after the first 
checkpoint, automatic restart will occur. 
Thus, if the user does not want automatic 
restart, he should always include the RD 
parameter with a code of either RD=NR or 
RD=NC, both of which suppress the automatic 
restart procedure. 
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If the programmer wishes his program to 
be restarted on a deferred basis, he should 
code the RD parameter as RD=NR. This form 
of the parameter suppresses automatic 
restart but allows a checkpoint record to 
be written provided a RERUN clause has been 
specified. At restart time, the programmer 
may choose to restart his program at a 
checkpoint other than at the beginning of 
the job step. 

The programmer may also elect to 
suppress both restart and writing 
checkpoints. By coding RD=NC, the 
programmer, in effect, is ignoring the 
features of the Checkpoint/Restart 
facility. 



Whenever automatic restart is to occur, 
the system will reposition all devices 
except unit-record machines. 



Deferred Restart 



Deferred restart may occur at any 
checkpoint, not necessarily the latest one 
taken. 



The programmer requests a deferred 
restart by means of the RESTART parameter 
on the JOB card and a SYSCHK DD statement 
to identify the checkpoint data set. The 
formats for these statements are as 
follows: 



Automatic Restart 



Automatic Restart occurs only at the 
latest checkpoint taken. (If no checkpoint 
was taken before interruption, Automatic 
Restart occurs at the beginning of the job 
step) . 



//jobname JOB , MSGLEVEL=1, X 

// RESTART^ ( request, [checkid] ) 

//SYSCHK DD DSNAME=data-set-name, X 
// DISP=OLD, UNIT-deviceno, X 

// VOLUME=SER=volser 



where: 



In order to restart automatically, a 
program must satisfy the following 
conditions. 



MSGLEVEL=1 (or MSGLEVEL=l 1, y) where y is 
either or 1) 
is required if restart is to occur in 
an MVT environment. 



• A program must request restart by using 
the RD parameter or by taking a 
checkpoint. 

• An ABEND that terminated the job must 
return a code eligible to cause 
restart. (For further discussion on 
this requirement, see the publication 
IBM OS Superviso r Services . ) 

• The operator authorizes the restart, 
with the following procedure: 

The system displays the following 
message to request authorization of the 
restart: 

XXIEF225D SHOULD 

jobname. stepname. procstep 
RESTART [checkid] 

The operator must reply in the 
following form: 

REPLY XX, ' {YES | NO | HOLD}' 

where YES authorizes restart, NO 
prevents restart, and HOLD defers 
restart until the operator issues a 
RELEASE command, at which time restart 
will occur. The HOLD option is 
applicable only in a multiprogramming 
environment. 



RESTART= (request, [checkid] ) 

identifies the particular checkpoint 
at which restart is to occur. Request 
may take one of the following forms: 

* to indicate restart at the beginning 
of the job 

stepname to indicate restart at the 
beginning of a job step 

stepname. procstep to indicate restart 
at a procedure step within the 
jobstep 

checkid 

identifies the checkpoint where 
restart is to occur. 



SYSCHK 

is the DDNAME used to identify a 
checkpoint data set to the control 
program. The SYSCHK DD statement must 
immediately precede the first EXEC 
statement of the resubmitted job, and 
must follow any JOBLIB statement. 



data- set-name 

must be the same name that was used 
when the checkpoint was taken. It 
identifies the checkpoint data set 
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deviceno and volser 

identify the device number and the 
volume serial number containing the 
checkpoint data set. 



As an example illustrating the use of 
these job control statements, a restart of 
the GO step of a COBUCLG procedure, at 
checkpoint identifier (CHECKID) C0000003, 
might appear as follows: 

//jobname JOB , MSGLEVEL=1, 



// RESTART= 

// (stepname. GO,C0000003) 

//SYSCHK DD DSNAME=CHEKPT, 

// DISP=OLD, UNIT=2400, 

// VOLUME=SER=llllll 



X 



following the restart step if they 
contain the form stepname or 
stepname. procstep referring to a step 
preceding the restart step. However, 
if these parameters are used, the 
preceding step referred to must be 
specified in the resubmitted deck. 

When a deferred restart has neen 
successfully completed, the system will 
display the following message on the 
console: 



TH.TfinfiT 



-inl-in^m^ 



RKSTARTF.D 



Control is then given to the user's program 
that executes in a normal manner. 



CHECKPOINT/RESTART DATA SETS 



{DD statements similar to original deck} 



The Restart routine uses information 
from DD statements in the resubmitted job 
to reset files for use after restart; 
therefore, care should be taken with any DD 
statements that may affect the execution of 
the restarted job step. Attention should 
be paid to the following: 

• During the original execution, a data 
set meant to be deleted at the end of a 
job step should conditionally be 
defined as PASS rather than DELETE in 
order to be available if an 
interruption forces a restart. If the 
restart is at the beginning of a step, 

a data set created in the original 
execution (defined as NEW on a DD 
statement) must be scratched prior to 
the restart. If the data set is not 
deleted, the DD statement must be 
changed to define it as OLD. 

• At restart time, input data sets on 
cards should be positioned as they were 
at the time of the checkpoint. Input 
data sets on tape or direct access 
devices will be automatically 
repositioned by the system. 

• At restart time, the EXEC statement 
parameters PGM and COND, and the DD 
statement parameters SUBALLOC and 
VOLUWE=REF must not be used in steDS 



If the RERUN clause was executed during 
the original execution of the processing 
program, checkpoint entries were written on 
a checkpoint data set. To resubmit a job 
for restart when execution is to be resumed 
at a particular checkpoint, an additional 
DD statement must be included. This DD 
statement describes the data set on which 
the checkpoint entry was written and it 
must have- the ddname SYSCHK^ The SYSCHK D0- 
statement must immediately precede the 
first EXEC statement of the resubmitted job 
and must follow the DD statement named 
JOBLIB, if one is present. 

For both deferred and automatic 
checkpoint/restart, if Direct SYSOUI Writer 
for the restarted job was active at the 
time the checkpoint was was taken, it must 
be available for the job to restart. For 
further information, see the publication 
IBM OS Operat o r' s Reference , Order 
No. GC28-6691. 



If the che 
multi volume, 
volume on whi 
written must 
parameter. I 
on a 7-track 
labels or no 
statement mus 



ckpoint data set is 

the sequence number of the 

ch the checkpoint entry was 

be included in the VOLUME 

f the checkpoint data set is 

magnetic tape with nonstandar; 

labels, the SYSChK DD 

t contain DCB=(TRTCH=C, . . . ) . 



Figure 109 illustrates a sequence of 
control statements for restarting a job. 



JOB 
DD 

DD 



EXEC 



MSGLEVEL=1,REGION=80K, RESTART= (STEP1, CHECKPT4) 
DSNAME=PRIV. LIB3, DISP=OLD 

DSNAME=CHKPTLIB,UNIT=2311,VOL=SER=456789, 
DISP= (OLD, KEEP) 
PGM=PROG4, TIWE=5 



j //PAYROLL 
| //JOBLIB 
j //SYSCHK 

I// 

| //STEP1 

L 

Figure 109. Restarting a Job at a Specific Checkpoint Step 
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If a SYSCHK DD statement is present in a 
job and the JOB statement does not contain 
the RESTART parameter, the SYSCHK DD 
statement is ignored. If a RESTART 
parameter without the CHECKID subparameter 
(as in Figure 91) is included in a job, a 
SYSCHK DD statement must not appear before 
the first EXEC statement for a job. 

Figure 110 illustrates the use of the RD 
parameter. Here, the RD parameter requests 
step restart for any abnormally terminated 
job step. The DD statement DDCKPNT defines 
a checkpoint data set. For this step, once 
a RERUN clause is executed, only automatic 
checkpoint restart can occur, unless a 
CHKPT cancel is issued. 



from the restarted job. The RESTART 
parameter has oeen added to the JOB 
statement and indicates that restart is to 
begin with the first job step. The DD 
statement WORK originally assigned a 
conditional disposition of KEEP for this 
data set. If this step did not abnormally 
terminate during the original execution, 
the data set was deleted and no 
modifications need be made to this 
statement. If the step did abnormally 
terminate, the data set was kept. In this 
case, define a new data set as shown in 
Figure 111, or change the data set's status 
to OLD before resubmitting the job. A new 
data set has also been defined as the 
checkpoint data set. 



Figure 111 illustrates those 
modifications that might be made to control 
statements before resubmitting the job for 
step restart. The job name has been 
changed to distinguish the original job 



Figure 112 illustrates those 
modifications that might be made to control 
statements before resubmitting the job for 
checkpoint restart. 



|//J1234 


JOB 


| //SI 


EXEC 


|//INDATA 


DD 


I// 




| //REPORT 


DD 


j //WORK 


DD 


I// 




| //DDCKPNT 


DD 



3 86, SMITH, MSGLEVEL=1, RD=R 

MYPROG 

DSNAME=INVENT,UNIT=2400, DISP=OLD, VOLUME=SER=91468 , 

LABEL=RETPD=14 

SYSOUT=A 

DSNAME=T91468,DISP=(, ,KEEP) , UNIT=SYSDA, 

SPACE=(3000, (5000, 500) ) , VOLUME= (PRIVATE, RETAIN, ,6) 

UNIT=24 00, DISP= (MOD, PASS, CATLG) , DSNAME=C91468 



Figure 110. Using the RD Parameter 



I//J3412 


JOB 


|//S1 


EXEC 


| //INDATA 


DD 


I// 




| //REPORT 


DD 


j //WORK 


DD 


I// 




| //DDCHKPNT 
L _ 


DD 


Figure 111. 


Modi 



3 86, SMITH, MSGLEVEL=1, RD=R, RESTART=* 

MYPROG 

DSNAME=INVENT,UNIT=2400,DISP=OLD, VOLUME=SER=91468 , 

LAEEL=RETPD=14 

SYSOUT=A 

DSNAME=S91468,DISP=(, ,KEEP) , UNIT=SYSDA, 

SPACE=(3000 r (5000, 500) ), VOLUME= (PRIVATE, RETAIN, , 6) 

UNIT=2400, DISP=(MOD, PASS, CATLG) , DSNAME=R91468 



Modifying Control Statements Before Resubmitting for Step Restart 
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I//J3412 


JOB 


|//S1 


EXEC 


| //SYSCHK 


DD 


| //INDATA 


DD 


I// 




| //REPORT 


DD 


| //WORK 


DD 


I// 




| //DDCKPNT 


DD 


Figure 112. 


Modi 



386, SMITH, MSGLEVEL=1,RD=R, RESTART=(*.C0000002) 

MYPROG 

DSNAME=C91468, DISP=OLD 

DSNAME=INVENT,UNIT=2400,DISP=OLD, 

VOLUME=SER=91468, LABEL=RETPD=14 

SYSOUT=A 

DSNAME=T91468,DISP=(, ,KEEP) , UNIT=SYSDA, 

SPACE=(3000, (5000, 500) ) , VOLUME= (PRIVATE, RETAIN, ,6) 

UNIT=2400,DISP= (MOD, KEEP, CATLG) , DSNAME=C91468 



Modifying Control Statements Before Resubmitting for Checkpoint Restart 



The job name has been changed to 
distinguish the original job from the 
restarted job. The RESTART parameter has 
been added to the JOB statement and 
indicates that restart is to begin with the 
first step at the checkpoint entry named 
C0000002. The DD statement DDCKPNT 
originally assigned a conditional 
disposition of CATLG for the checkpoint 
data set. If this step did not abnormally 



terminate during the original execution, 
the data set was kept. In this case, the 
SYSCHK DD statement must contain all of the 
information necessary to retrieve the 
checkpoint data set. If the job did 
abnormally terminate, the data set was 
cataloged. In this case, the only 
parameters reguired on the SYSCHK DD 
statement, as shown in Figure 112, are the 
DSNAME and DISP parameters. 



Using the Checkpoint/Restart Feature 333 



USING THE TELEPROCESSING FEATURE 



A teleprocessing environment consists of 
a central computer 1 , remote or local 2 
stations, and communication lines between 
such stations and the central computer. 
Use of the Teleprocessing Feature (TP) 
enables the COBOL programmer to create 
device-independent programs for 
teleprocessing applications. 

Teleprocessing applications require a 
special, user-written assembler-language 
program that controls the flow of data 
between the central computer and the remote 
stations. This message control program 
(MCP) also performs such additional tasks 
required only in a TP environment as 
dial-up, polling, (or contacting each 
remote station) , and synchronization, as 
well as such device-dependent tasks as 
character translation and insertion of 
control characters. 

The MCP consists of routines that 
identify the teleprocessing network to the 
operating system, establish line control 
between the computer and the various kinds 
of stations, and process messages in a way 
tailored to meet the needs of the user. A 
"message" is the data flowing either from a 
remote station to the central computer or 
from the central computer to a remote 
station. Each unit of data representing a 
message is terminated by a control 
character. An MCP is required in a 
teleprocessing system operating under TCAM. 

Depending on the needs of the 
installation, one or more COBOL programs 
may be required to process the contents of 
the messages. An example of a job needing 
no application program is message 
switching, an operation consisting only of 
forwarding messages unaltered (except for 
such processing as the MCP may perform) to 
one or more other stations. 

The MCP itself can perform limited 
processing (for example, examination of the 
first portion of a message to determine 
certain routine information and message 



*-A System/360, at least a Model 40, or a 

System/370 model with a minimum of 128K 

bytes of main storage. 
2 A station whose control unit is connected 

directly to a computer data channel by a 

local cable. 



code translation) . Further, the MCP can 
obtain the time of day a message is 
received from a station and transmit this 
information to a COBOL program. It can 
also check the input messages to determine 
whether an error message should be sent to 
the designated station. 

This section describes the flow of a 
single-segment message through a system 
operating under TCAM, from the time it is 
entered at the remote station to its 
transmission to a destination station. 
Figure 113 outlines the flow of a message 
segment through a TCAM system. The 
encircled numerals in the flow diagram 
correspond to the steps listed in the 
description that follows. 

Because of the possible variety of both 
message types and destinations, it is often 
helpful for the user to precede the message 
"text" with a message "header" so that the 
user can transmit to the MCP information 
essential to handling the text. It is the 
user who determines which part of the 
message is the header and which part is the 
text. 

Steps 1 and 2 ; The input message is 
prepared at the remote station and entered 
on the line. The message may be keyed in, 
or it may be entered from a card or tape 
reader. The originating station enters the 
message via a communication line, the 
transmission control unit, and the 
multiplexor channel. 

Step 3: The message enters the central 
computer and is stored, together with the 
internally generated buffer prefix, in a 
main storage buffer. As message data fills 
the buffer, TCAM inserts the necessary 
control information in the prefix. Before 
the message characters are placed in the 
first buffer, TCAM may reserve space in the 
buffer for later insertion of the time, 
date, and sequence number for the message, 
and for the screen control character for 
the IBM 2260 and 2265 remote display 
complexes, if appropriate. Once a buffer 
is filled with the first segment of the 
message, the MCP controls the flow of the 
buffer through the teleprocessing network. 
The heart of the MCP consists of the 
message handlers (MH) constructed by the 
user to process messages from the various 
lines or line groups. 
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Step U: The incoming message is routed to 
the incoming group of the MH specified for 
the line (by the MH= operand of the DCB 
macro for the line group in which the line 
is included) . The message is passed, a 
buffer at a time, through the incoming 
group, which performs such user-selected 
functions on the message header as origin 
checking, and input sequence-number 
checking. Similarly, such functions may be 
performed for the message segment as 
translating the segment from line code to 
EBCDIC and causing an error message to be 
sent to the originating station when the 
incoming group detects any user-specified 
error in the segment. In performing its 
functions, the incoming group of the MH 
scans and processes header fields based on 
the relative order of the individual MH 
macro instructions. The incoming group 
then routes the message to the destination 
queue. 

Step 5 : After processing by the incoming 
group, the message is placed on a 
destination queue for either the COBOL 
program, for processing, or an accepting 
station. (If no message processing is 
necessary, the next action performed is 
that described in Step 13. ) All messages 
requiring text processing are routed to the 
destination queue for the COBOL program 
that processes that type of message. The 
user controls this routing via the message 
header by placing the name of the 
destination queue for the COBOL program in 
a destination field of the message header 
or by MH macro instructions such as MSGTYPE 
that may be used to direct messages of a 
particular type to a particular queue. 

Step s 6, 7, and 8 : The message from a 
destination queue for a COBOL program is 
placed in a main-storage buffer; the 
outgoing group of an MH (the MH is created 
especially for the application program and 
is assigned to it by the MH= operand of the 
PCB macro in the MCP) places it on the 
read-ahead queue, a special queue that 
allows overlap of MCP and application 
program processing of messages queued for a 
particular destination. 

Step 9: Each time the COBOL program issues 
a RECEIVE statement, TCAM passes message 
data from the read-ahead queue to a 
user-specified work area in the COBOL 
program. As the message data is moved to 
the work area, TCAM removes the header or 
text prefix from the buffer. After 
receiving the message data, the COBOL 
program processes it as required and then 
generates a response message, if any is to 
be returned to a station. The destination 
queues act as buffers between the COBOL TP 
program and the remote stations. Thus, the 
COBOL TP program can accept messages from 
MCP destination queuse and place these 



messages in MCP destination queues as if 
the queues were sequential files within a 
conventional COBOL program. (The sample 
COBOL program TESTTP1 , shown in Figure 118, 
reads a sequential file and then sends each 
record to a destination queue, creating a 
TCAM data set for the COBOL TP program 
TESTTP2, shown in Figure 119, making it 
possible to test a COBOL TP program without 
terminals. ) 



Ste ps 1 and 11: When the COBOL program 
issues a SEND statement, TCAM moves the 
data from the work area into an MCP buffer 
before it is handled by the incoming group 
of the MH designed for the COBOL program. 
A header or text buffer prefix is created 
when data is moved to the buffer, as for 
other incoming messages. As the message 
data fills the buffer, TCAM inserts control 
information in the prefix field. Ihe 
response message generated by an 
application program can be any 
user-selected length. After the buffer is 
filled, the message is handled by the 
incoming group of the MH assigned to the 
application program by the MH= operand of 
the PCB macro instruction that provides an 
interface between the MCP and the COBOL 
program. 



Step 12: If further processing of the 
message is required in anotner application 
program, the message is queued for tnat 
destination (and Steps 5 through 11 are 
repeated). If however, no other 
application program processing is needed, 
the processed message is placed on the 
destination queue for an accepting station. 
The destination is that specified by the 
COBOL programmer in the file referenced by 
the SYMBOLIC DESTINATION clause of the 
output CD. It may be for an application 
program or a station. 

Step 1 3: The destination queue for an 
accepting station, like the destination 
queue for an application program, is a part 
of the message queues data set. TCAM 
obtains message segments from the 
destination queue on a first-ended 
first-out (FEFO) basis within priority 
groups. 

Step_s_lU _and_l 5 : The message segment is 
placed in a buffer, and the outgoing group 
of the MH specified for the line processes 
the message. The MH performs such 
user-selected functions as converting the 
code of the message to the transmission 
code for the station (if necessary), 
inserting the time and data in the header, 
logging messages, and updating message 
counts. These operations are performed in 
the buffers that receive the message 
segments from the destination queue. 
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S tep 16: TCAM transmits the message, minus 
the header and text prefixes, to the 
appropriate station. 



WRITING A MESSAGE CONTROL PROGRAM 



The COBOL programmer can write a message 
control program (MCP) designed specifically 
for his teleprocessing needs using 
telecommunications access methods (TCAM) 
macro instructions. Using a group of TCAM 
macro instructions, the user follows in 
general the coding requirements and 
restrictions of any other 
assembler-language macro instruction. 
Guidelines for writing an MCP are contained 
in the IBM OS Teleco m munications Access 
Meth o d (TCAM) Pro gr ammer's Guide and 
Reference Manual . The user must tailor 
these general statements to meet the needs 
of the installation. 

The sample message control program that 
appears in Figure 114 in this chapter is a 
hypothetical program designed for specific 
COBOL applications. The needs of the user 
will undoubtedly vary from installation to 
installation. Nevertheless, the sample MCP 
together with the sample COBOL "programs 
TESTTP1 and TESTTP2 (shown in Figures 118 
and 119) can serve as an excellent example 
of COBOL programs and an MCP written for 
teleprocessing applications. 



• Place response messages generated by 
application programs on queues for 
subsequent transmission 

• Retrieve messages from destination 
queues and prepare them for 
transmission to remote stations 

• Perform message-editing functions for 
outgoing messages 

• Take periodic checkpoints of the system 

• Provide operator-to-system 
communications through system control 
terminals 

• Initiate corrective action when an 
error or unusual condition is detected 

• Cancel incoming messages containing 
errors 

• Reroute messages with erroneous control 
information to a special queue 

• Transmit error messages 

However, not all of these functions are 
required of an MCP. Many of the optional 
TCAM macros allow the user to write an MCP 
that includes functions that would 

otherwise" have" to" "be" executed" by the COBOL 

program. There are, nevertheless, some 
functions the MCP must always provide and 
in so doing follow certain conventions. 
These requirements are discussed under 
"User Tasks. " 



FUNCTIONS OF THE MESSAGE CONTROL PROGRAM 

Depending on the requirements of the 
installation, the user can create an MCP to 
perform any of the following functions: 

• Enable and disable communication lines 

• Invite terminals to transmit messages 

• Receive messages from terminals 

• Dynamically assign buffers to incoming 
messages 

• Handle messages on the basis of 
user-specified priorities 

• Perform message-editing functions for 
incoming messages 

• Determine the appropriate destination 
queue for a message and route the 
message to that queue 

• Queue the message in the appropriate 
destination queue 



USER TASKS 



Guidelines for writing an MCP are 
contained in the publication I BM O S Access 
Method (TCAM) Programmer's Guide and 
Refere nce Manual . The user must tailor 
these general statements to meet the 
specific needs of his installation. For 
example, a message can be transmitted from 
one terminal to another, from a terminal to 
an application program, or from one 
application program to another. Moreover, 
the message may contain any one of several 
types of data. 

Regardless of the specific requirements 
of the user, the MCP writer must always be 
concerned with four major tasks, as 
follows: 

• Defining the core storage buffers used 
by the MCP for handling, queueing, and 
transferring message data between 
communication lines and queueing 
devices. 
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• Defining the data sets referred to by 
the MCP, and providing for their 
activation and deactivation. 

• Defining the various terminal and line 
control areas used by the MCP (that is, 
the operating procedures and signals by 
which a teleprocessing system is 
controlled) . 

• Defining the message handlers (the sets 
of routines that examine and process 
control information in message headers, 
prepare message segments for forwarding 



to their destination, and route 
messages to their proper destination). 

In carrying out each of these tasks, tne 
user codes a variety of assembler-language 
macros in a specified oraer. Some of these 
macros must be included in every MCP; 
others the user specifies according to the 
needs of his installation. Required as 
well as optional macros are illustrated in 
the sample MCP given in Figure 114. The 
encircled numerals in the discussion that 
follows refer to sections of code that are 
similarly labeled in the figure. 



338 



LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

1 *** 

2 * 

3 * MESSAGE CONTROL PROGRAM 

4 * 

000000 5 MCP CSECT 

6 PRINT NOGEN 

7 * 

8 * IN THE FOLLOWING MACRO — 

9 * PROGID MAY BE OMITTED — IF USED, IT IS PLACED AT THE 

10 * BEGINNING OF THE EXECUTABLE CODE IN THE MCP 

11 * DISK=YES IS THE ASSUMED OPERAND — IF NO MESSAGE QUEUES DATA 

12 * SETS ARE ON DISK, CODE DISK=NO 

13 * CPB= USED IN READING FROM AND WRITING TO DISK — NEEDED IF 

14 * DISK=YES — NO. DEPENDS ON NO. OF LINES, AMOUNT OF MESSAGE 

15 * TRAFFIC AND SIZE OF BUFFER UNITS 

16 * CIB=NO. OF COMMAND INPUT BLOCKS — BUFFER- LIKE AREAS USED TO 

17 * CONTAIN OPERATOR CONTROL MESSAGES FROM SYSTEM CONSOLE — 

18 * FREED ONCE A MESSAGE PROCESSED — 2 ASSUMED AND MAX. IS 255 

19 * PRIMARY=SYSCON — THIS IS ASSUMED AND SPECIFIES THE SYSTEM 

20 * CONSOLE AS THE PRIMARY OPERATOR CONTROL TERMINAL FOR 

21 * ENTERING AND ACCEPTING OPERATOR CONTROL MESSAGES — IF A 

22 * TERMINAL IS SPECIFIED, IT MUST BE ON A NON- SWITCHED LINE 

23 * AND BE ABLE TO ACCEPT AND ENTER MESSAGES 

24 * CONTROL= — USED TO IDENTIFY OPERATOR CONTROL MESSAGES TO SYSTEM 

25 * WHEN RECEIVED FROM OTHER THAN SYSTEM CONSOLE — IS DEFAULT 

26 * AND IS VALID ONLY IF ALL OPERATOR COMMANDS ARE TO BE 

27 * ENTERED FROM SYSTEM CONSOLE 

28 * KEYLEN= — SIZE OF BUFFER UNIT — BETWEEN 33 AND 255 — 

29 * CAN ALSO SPECIFY BY UNITSZ= RATHER THAN KEYLEN= 

30 * LNUNITS= — NO. OF BUFFER UNITS TO BE USED IN BUILDING BUFFERS 

31 * FOR INCOMING AND OUTGOING MESSAGE SEGMENTS — IF TOO FEW ARE 

32 * SPECIFIED, INCOMING MESSAGE DATA MAY BE LOST — TOO MANY 

33 * WASTES STORAGE SPACE 

34 * MSUNITS= — NEEDED IF HAVE MAIN STORAGE MESSAGE QUEUES DATA SET 

35 * — NO. OF BUFFER UNITS ASSIGNED TO THIS DATA SET — IF NO DISK 

36 * BACK-UP IS SPECIFIED, MESSAGE SEGMENTS FAY BE LOST IF NOT 

37 * ENOUGH UNITS 

38 * MSMAX= — PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES 

39 * DATA SET WANT USED BEFORE BIT IN ERROR RECORD SET — 
4.0 * 7Q. ASSUMED 

41 * MSMIN= — PERCENTAGE OF UNITS IN MAIN STORAGE MESSAGE QUEUES 

42 * DATA SET WANT UNUSED BEFORE BIT SET NOTIFYING NO LONGER 

43 * CROWDED — MUST BE LESS THAN MSMAX — 

44 * 50 ASSUMED 

45 * (NOTE — THIS BIT ALWAYS SET IF SPECIFIED PERCENTAGE OF UNITS 

46 * UNUSED) 

47 * DLQ= — OPTIONAL — USED TO SPECIFY A TERMINAL TO RECEIVE MESSAGES 

48 * HAVING INVALID DESTINATIONS AS DETERMINED BY FORWARD MACRO 

49 * INTVAL= — AN OPERATOR CONTROL MESSAGE TELLS TCAM TO ENTER THIS 

50 * DELAY TO MINIMIZE UNPRODUCTIVE POLLING — WEEN ALL MULTIPOINT 

51 * LINES ARE INACTIVE, THE INTERVAL COMMENCES — LINES TO 

52 * SWITCHED STATIONS AND NONSWITCHED CONTENTION LINES LEFT 

53 * ACTIVE — THE OPERATOR COMMAND IS A MODIFY COMMAND REFERRED 

54 * TO AS ■ INTERVAL* --THE NO. SPECIFIES THE NO. OF SECONDS 

55 * STARTUP=-IF THIS OPERAND IS OMITTED, THE USER WILL BE GIVEN 

Figure 114. A Message Control Program for Teleprocessing Application (Part 1 of 20) 



Using the Teleprocessing Feature 339 



© 



LOC OBJECT CODE ADDF1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

56 * THE OPPORTUNITY TO SPECIFY IT AT INITIALIZATION TIMF AND 

57 * HE MAY ALSO CHANGE OTHER INTRO OPERANDS—CY MEANS ALWAYS 

58 * A COLD START — W SPECIFIES A WARM START AFTER A QUICK OR 

59 * FLUSH CLOSEDOWN AND A CONTINUATION AFTER A SYSTEM FAILURE 

60 * — W INDICATES THE CONTINUATION RESTART WILL INCLUDE FULL 

61 * SCANNING OF THR QUEUES — WY IS THE SAME AS W EXCEPT NO 

62 * SCANNING OF THE QUEUES FOR ALREADY SENT MESSAGES IS DONE — 

63 * — A CHECKPOINT DATA SET IS NEEDED FOR ANYTHING BUT A COLD 

64 * START — ALSO, IF DD CARD FOR CHECKPOINT DATA SET SPECIFIES 

65 * DISP=NEW, WILL GET A COLD START REGARDLESS 

66 * OLTEST=IF DO NOT WISH ON-LINE TEST FACILITY — CODE 

67 * FFATURE= THE DEFAULTS ARE DIAL, 2741, AND TIMER — SINCE WE DO 

68 * NOT HAVE A 2741 TERMINAL, WE ARE CODING TO INDICATE THIS 

69 * LINETYP= STSP SPECIFIES START-STOP LINES ONLY, BISC SPECIFIES 

70 * BSC LINES ONLY, MINI SPECIFIES ALL TERMINALS ARE IBM 1050 

71 * ON LEASED LINES, BOTH IS DEFAULT AND INDICATES ALL TYPES 

72 * OF LINES ARE SUPPORTED — IF THE LINES IN THE SYSTEM DO MOT 

73 * FALL UNDER THE 'BOTH' CATEGORY, SPACE IS SAVED EY CODING 

74 * THIS OPERAND 

75 * DTRACE — PUT IN FOR TESTING ONLY TEST * 

76 * 

77 INTRO PROGID=MCP,DISK=YES,CPB=10,CIB=2,PRIMARY=SYSCON, X 
CONTROL=TCAM, KEYLEN=100, LNUNITS=20, MSUNITS=50, MSMAX=7S, X 
MSMIN=50,DLQ=T1, INTVAL=1200, STARTUP=W, OLTEST=0, X 
FEATURE- (DIAL, N02741, TIMER) , LINETYP=BOTH, X 

DTRACE=700 

309 * 

310 * TEST IF INTRO MACRO WORKED SUCCESSFULLY 
000512 12FF 311 LTR 15,15 

000514 4780 D520 00528 312 BZ OPENFILE YES 

313 ABEND ABEND 123, DUMP INTRO OR AN OPEN FAILED 

321 * 

322 * THE MESSAGE QUEUES DATA SET MUST BE OPENED FIRST IF IT RESIDES ON 

323 * DISK — A MAIN STORAGE MESSAGE QUEUES DATA SET IS NOT OPENED 
Q) 324 OPENFILE OPEN (MSGQ, (INOUT)) (5) 

000532 9110 D738 00740 330 TM MSGQ+48, X' 10' ^ CHECK IF OPEN SUCCESSFUL 

000536 47E0 D510 00518 331 BNO ABEND BRANCH IF NOT 

332 * 

333 * IF THE CHECKPOINT DATA SET IS USED, IT MUST BE OPENED NEXT 

334 OPEN (CHKPT, (INOUT)) (b) 

000546 9110 D764 0076C 340 TM CHKPT+48, X" 10* ^^ CHECK IF OPEN SUCCESSFUL 

00054A 47E0 D510 00518 341 BNO ABEND BRANCH IF NOT 

342 * 

343 * OPEN LINE GROUP DATA SETS — LINES WILL BE ACTIVATED SINCE IDLE NOT 

344 * SPECIFIED 

345 * NOTE — WE ARE NOT CHECKING FOR OPEN ERRORS FOR THE LINES — SINCE THERE 

346 * IS PROBABLY NO NEED TO STOP THE SYSTEM IF SOME OF THE LINES ARE NOT 

347 * WORKING — MESSAGES WILL BE PRINTED ON THE SYSTEM CONSOLE FOR LINES 

348 * THAT ARE NOT WORKING — 

349 * IF A LINE BECOMES OPERATIONAL DURING A RUN, IT CAN THEN BE STARTED 

350 * BY THE VARY COMMAND USED TO START A LINE WHICH IS OPENED AS IDLE 

351 OPEN (LN1050, (INOUT), LNTWX, (INOUT)) (c) 

359 * W 

360 * OPEN LOG DATA SET (d) 

361 * V - y 

Figure 114. h Message Control Program for leleprocf-ss.in Replications (Fart 2 cf 20* 
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LOC OBJECT CODE 



ADDRl ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



00056A 9110 D7FC 
00056E 47E0 D510 



00057E 9110 D854 
000582 47E0 D510 



00060E 58DD 0004 



00804 



0085C 



OPEN (MSGLOG, (OUTPUT)) 
TM MSGLOG+ 4 8 , X' 1 ' 
BNO ABEND 



CHECK IF OPEN SUCCESSFUL 
BRANCH IF NOT 



362 

368 
00518 369 

370 * _ TEST*** 

371 

377 
00518 378 

379 * 

380 * ISSUE THE FOLLOWING BETWEEN THE OPENING AND CLOSING OF THE DATA SETS 
(3)381 READY 



OPEN (DUMP, (OUTPUT) ) (e) FOR SNAPS 

TM DUMP+48,X' 10* CHECK IF OPEN SUCCESSFUL 

BNO ABEND BRANCH IF NOT 



398 * 
399 
411 * 



TEST*** 



SNAP DCB=DUMP , PDATA=ALL 

(4) 412 * CLOSE DATA SETS 

^^ ii"! T CLOSE (LN 1 050 I 

CLOSE (DUMP,DISP> (b) 

CLOSE (MSGLOG, DISP) (c) LOG DATA SET 



v^ 



LINE GROUP DATA SETS 
SNAP DATA SET 



TEST*** 



CLOSE (CHKPT,DISP) f£\ 



421 * 
422 
428 * 
429 

435 * 

436 * ALWAYS CLOSE CHECKPOINT DATA SET NEXT TO LAST 
437 

443 * 

444 * THF MESSAGE QUEUES DATA SET MUST ALWAYS 3B CLOSED LAST 

445 CLOSE (MSGQ.DISP) (^) 

451 * ^ 

452 * RETURN TO OS SUPERVISOR 

00004 453 L 13,4(13) PICK UP ADDRESS OF SYSTEM SAVE AREA SAVED 

454 * IN IEDSAVE1 — ADDRESS OF IEDSAVE1 WAS PUT 

455 * IN REG. 13 WHICH WAS MADE BASE REGISTER 
(?) 456 RETURN (14,12),RC=0 

^ 460 * 



Figure 114. A Message Control Program for Teleprocessing Applications iPart 3 of 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 
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1*62 
463 
464 
465 
466 
467 
468 
469 
470 
471 
472 
473 
474 
475 
476 
477 
478 
479 
480 
481 
482 
483 
484 
485 
486 
487 
488 
489 
490 
491 

526 
527 
528 
529 
530 
563 
564 
565 
566 
567 
568 
569 
602 
603 
604 
605 
606 
607 
608 
609 
610 
611 
643 
644 



* DATA DEFINITIONS — PROCESS CONTROL BLOCKS AND DATA CONTROL BLOCKS 



* PCB — PROCESS CONTROL BLOCK — USED TO COMMUNICATE BETWEEN THE KCP 

* AND AN APPLICATION PROGRAM — 

* ONE PCB IS NEEDED FOR EACH ACTIVE APPLICATION PROGRAM 
* 

* IN THE FOLLOWING MACRO — 

* MH= GIVES THE SYMBOLIC ADDRESS OF THE MESSAGE HANDLER FOR THIS 

* APPLICATION PROGRAM 

* BUFSIZE= SPECIFIES SIZE OF BUFFERS TO HANDLE MESSAGES FOR 

* APPLICATION PROGRAM 

* BUFIN= INITIAL NO. OF BUFFERS INTO WHICH USERS WRITE WORK AREA 

* EMPTIED—OPTIMUM NO. IS ENOUGH FOR ALL OF WORK AREA — BETWEEN 

* 2 AND 15 — 2 ASSUMED 

* BUFOUT= INITIAL NO. OF BUFFERS THAT MAY BE FILLED IN ANTICIPATION 

* OF A READ — BETWEEN 2 AND 15 — 2 ASSUMED 

* RESERVE=NO. OF BYTES TO RESERVE FOR INSERTION OF CHARS. BY DATE! I > 

* AND SEQUENCE MACROS FOR MESSAGES COMING FROM APPLICATION PROGRAf- 

* DATE=YES — THIS IS NEEDED FOR ALL PCB ENTRIES FOR A COBOL PROGRAM. 

* THIS WILL MAKE THE DATE AND TIMS AVAILABLE SO IT MAY BE PLACED 

* IN THE COBOL PROGRAM INPUT CD — (IT IS ALSO NEEDED ON AN INPUT 

* TPROCESS ENTRY) 
* 

* PROCESS CONTROL BLOCK FOR COBOL PROGRAM RUNNING WITH TERMINALS 

PCBLK PCB^- / MH=MHTRMAPP,BUFSIZE=100,BUFIN=2,BUFOUT=5,RESERVE=21 1 

DATE=YES 
* 

* PROCESS CONTROL BLOCK FOR COBOL PROGRAMS THAT SIMULATE TERMINAL 

* INPUT DATA — USED FOR TESTING WITHOUT TERMINALS 

(5) 

PCBLKl PCB v - ,/ MH=MHAPPAPP, BUFSIZE=100, BUFIN=2, BUFOUT=5, DATE=YES 
* 

* PROCESS CONTROL BLOCK FOR COBOL PROGRAMS TESTING MESSAGES SENT TO 

* DESTINATIONS DEFINED BY A QUEUE STRUCTURE 
* 

* IT USES THE SAME MH THAT PCKBLK1 USES 

(?) 
PCBLK2 PCB^MH=MHAPPAPP, BUFSIZE=100, BUFIN=2, BUFOUT=5, DATE=YES 
* 

* DCBS 

* DCB FOR MESSAGE QUEUES DATA SET 

* IN THE FOLLOWING MACRO — 

* OPTCD=R SPECIFIES REUSABLE DISK — IF NON-REUSABLE, SPECIFY L 

* THRESH= SHOULD PROBABLY BE USED IF NON-REUSABLE DISK— 

* SPECIFIES PERCENTAGE OF RECORDS TO BE USED BEFORE A FLUSH 

* CLOSEDOWN INITIATED — A CERTAIN PERCENTAGE ASSUMED 
MSGQ DCB/^vDSORG=TQ, MACRF= (G, P) , DDNAME=QFILE, OPTCD=R 

* K*J 

* DCB FOR THE CHECKPOINT DATA SET 



Figure 114. A Message Control Program for Teleprocessing Applications (Part 4 of 20 ) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



645 
677 
678 
679 
680 
681 
682 
683 
684 
685 
686 
687 
688 
689 
690 
691 
692 
693 
694 
695 
696 
697 
698 
699 
700 
701 
702 
703 
704 
705 
706 
707 
708 
709 
710 
711 
712 
713 
714 
715 
716 



753 
754 
755 
756 
757 



794 
795 
796 
797 
798 



CHKPT DCB/--N DSORG=TQ , MACRF= ( G , P ) , DDNAME=CFILE , OPTCD=C 

* O 

* DCB FOR THE 1050 LINE GROUP 

* IN THE FOLLOWING MACRO — 

* CPRI=R INDICATES THAT RECEIVE HAS PRIORITY OVER SENDING — 

* S INDICATES THAT SENDING HAS PRIORITY OVER RECEIVING — 

* E INDICATES EQUAL PRIORITY — 

* FOR SWITCHED LINES, S MUST BE SPECIFIED 

* BUFIN=NO. OF BUFFERS TO ASSIGN INITIALLY FOR RECEIVING FOR 

* EACH LINE — 1 ASSUMED — 15 MAXIMUM 

* BUFOUT=NO. OF BUFFERS TO ASSIGN INITIALLY FOR SENDING FOR 

* EACH LINE — 2 ASSUMED — 15 MAXIMUM 

* BUFMAX=MAX. NO. OF BUFFERS TO BE USED FOR DATA TRANSFER FOR 

* EACH LINF IN LINE GROUP — NO LESS THAN LARGER OF BUFIN AND 

* BUFOUT — 15 MAXIMUM 

* BUFSIZE=BUFFER SIZE IN BYTES USED FOR ALL LINES IN THIS LINE 

* GROUP — SIZE SHOULD BE A MULTIPLE OF THE BUFFER UNIT SIZE 

* SPECIFIED IN KEYLEN= OPERAND OF INTRO MACRO — (MAY BE 

* OVERRIDDEN ON A STATION BASIS BY BUFSIZE= OPERAND OF THE 

* TERMINAL MACRO) 

* INVLIST=NAMES OF INVITATION LISTS FOR LINES OF LINE GROUP 

* — INVITATION LIST NAMES ARE SPECIFIED ACCORDING TO THE 

* ASCENDING RELATIVE LINE NOS. OF THE LINES IN THE GROUP 

* MH=ADDRESS OF MESSAGE HANDLER 

* PCI=SPECIFIES IF AND HOW A PROGRAM- CONTROLLED INTERRUPTION 

* TO BE USED FOR BUFFER ALLOCATION AND DEALLOCATION — 1ST 

* SUBOPERAND REFERS TO RECEIVING AND 2ND TO SENDING — 

* N SPECIFIES NO PCIS — R SPECIFIES AFTER 1ST BUFFER, COMPLETED 

* BUFFER DEALLOCATED — A IS ASSUMED AND SPECIFIES AFTER 1ST 

* BUFFER, COMPLETED BUFFER DEALLOCATED AND ANOTHER BUFFER IS 

* ALLOCATED 

* R£SEPVE=NO. OF BYTES TO RESERVE FOR INSERTION OF CHARS. BY 

* DATETIME AND SEQUENCE MACROS 

* TRANS=TRANSLATION TABLE 

* SCT=SPECIAL CHARACTERS TABLE 

* (IF CPRI=R AND NON- SWITCHED LINE, NEED INTVL= OR NO MESSAGES 

* ARE SENT — INTVL=NO. OF SECONDS TO DELAY AFTER PASS THRU 

* INVITATION LIST — NO LARGER THAN 255 — TOO SHORT A DELAY CAUSES 

* MESSAGES TO ACCUMULATE) 

*- - {£) _.- _ _._ _ 

LN1050 DCB\-'DSORG=TX,MACRF=(G,P),CPRI=S,DDNAME=LNl,BUFIN^"2, > 

BUFOUT=4,BUFMAX=4,BUFSIZE=100, INVLIST=(LIST1050) , > 
MH=MH1050,PCI=(A,A),RESERVE=21,TRANS=105F,SCT=105F 

* 

* DCB FOR THE TWX LINE — SEE DESCRIPTION OF OPERANDS BEFORE DCB FOR 

* 1050 — LN1050 

LNTWX DCB v - y DSORG=TX r MACRF=(G,P),CPRI=S,DDNAME=LN2,BUFIK=2, > 

BUFOUT=4,BUFMAX=4,BUFSIZE=100, INVLIST= (LISTTWX) , >. 
MH=MHTWX, PCI= (A f A) r RESERVE=21- TRANS=TTYC, SCT=TTYC 

* 

* DCB FOR LOG DATA SET 

* IN THE FOLLOWING MACRO — * 

* BLKSIZE= — THE VALUE SHOULD BE THE SAME AS IN KEYLEN OPERAND OF 

* INTRO MACRO * 



LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



NCP= — MAX. NO. OF BUFFER UNITS THAT MAY APPEAR IN A BUFFER * 



799 * 

800 * 

801 MSGLOG DCB^DSORG=PS,MACRF=(W),DDNAME=LOGFILE,BLKSIZE=100 f RECFM=F, *X 

NCP=2 * 

852 * TEST*** 



£g} 853 * DCB FOR SNAPS 



854 DUMP DCB DSORG=PS,RECFM=VBA, MACRF= (W) , LRECL=125, DDNAME=LRDUMP , *X 
BLKSIZE=882 * 



Figure 114. A. Message Control Program for Teleprocessing Applications (Part 5 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT7 5/03/72 

906 **** 

907 * 

908 * TERMINAL AND LINE CONTROL — DEFINES TERMINAL TABLE ENTRIES AND THE 

909 * INVITATION LISTS FOR EACH LINE 

910 * 

911 **** 
312 * 

913 * DEFINE THE TERMINAL TABLE 

914 * LAST= NAME OF LAST ENTRY IN TABLE 

915 * MAXLEN= NUMBER OF CHARACTERS IN LONGEST NAME 

916 * 

917 TTABLE LAST=D1, MAXLEN=5 

945 * NOTE* 

946 * IF ANY OPTION MACROS ARE NEEDED, THEY GO HERE — DATA GOES IN ENTRIES * 

947 * USING THE OPDATA= OPERAND OF THE TERMINAL OR TPROCESS ENTRIES 

948 * 

949 * ENTRY FOR 1050 TERMINAL 

950 * IN THE FOLLOWING MACRO — 

951 * QBY= T SPECIFIES THAT OUTGOING MESSAGES ARE TO BE QUEUED BY 

952 * TERMINAL — USE L IF BY LINE 

953 * — MUST QUEUE BY TERMINAL IF A SWITCHED STATION OR A 

954 * BUFFERED TERMINAL 

955 * DC3= DCBNAME FOR LINE 

956 * RLN=RELATIVE LINE NO. WITHIN THE LINE GROUP OF THIS LINE 

957 * TERM=SPECIFIES TYPE OF TERMINAL 

958 * QUEUES=MR SPECIFIES MESSAGE QUEUES KEPT IN MAIN STORAGE WITH 

959 * BACKUP ON REUSABLE DISK 

960 * ADDR=6213 IS A9 IN 1050 CODE — USED WHEN COMPUTER HAS MESSAGE 

961 * TO SEND — 9 IS CODE FOR ANY OUTPUT DEVICE 

962 * ALTDEST=IS NEEDED BECAUSE THIS IS REUSABLE DISK — NEEDED SO 

963 * MESSAGE IS NOT DISCARDED AT ZONE CHANGEOVER 

964 * NTBLKSZ= THE NO. OF CHARS. BETWEEN INSERTION OF EOB CHARS. 

965 * IN OUTPUT MSG. WHEN MSGFORM CODED IN OUTHDR 

©966 * Hi) 

967 Tl TERMINAI>-^QBY=T, DCB=LN1050,RLN=1,TERM=1050, QUEUES=MR, X 
ADDR=6 21 3 , ALTDEST=T1 , NTBLKSZ= ( 120 ) 

1001 * 

1002 * DEFINE ENTRY FOR THE SWITCHED TWX LINE WHICH CAN BE USED BEFORE AN 

1003 * ORIGIN MACRO IS ISSUED TO IDENTIFY THE STATION 

1004 * UTERM=YES IDENTIFIES THIS AS SUCH AN ENTRY 

1005 * THIS MACRO MUST PRECEDE ALL TERMINAL MACROS FOR STATIONS ON LINE 

1006 * IN THE FOLLOWING MACRO — 

1007 * ALWAYS SPECIFY DCB NAME, RELATIVE LINE NO., TERMINAL TYPE, 

1008 * AND QUEUES 

1009 * — ADDR= MIGHT BE CODED IF STATION HAD ADDRESSING CHARS. — IF 

1010 * USED, ALL STATIONS ON LINE MUST HAVE IDENTICAL ADDRESSING 

1011 * CHARACTERS 

1012 * (b) 

1013 T2A TERMINAI/*^LJTERM=YES,DCB=LNTWX,RLN=1,TERM=3335,QUFUES=MR 

1041 * 

1042 * TERMINAL ENTRY FOR TWX TERMINAL — SEE DESCRIPTION OF MOST OF OPERANDS 

1043 * PRECEDING TERMINAL MACRO FOR 1050 

1044 * IN ADDITION — 

1045 * DIALNO= SPECIFIES TELEPHONE NO. OF STATION AND MUST BE 

1046 * SPECIFIED FOR SWITCHED STATIONS — CODE 'NONE' IF NO AUTO 

Figure 114. h Message Control Program for Teleprocessing Applications (Part 6 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

1047 * CALL FEATURE 

1048 * ADDR= IS NOT GIVEN SINCE THIS STATION IS ON A SWITCHED LINE 

1049 * NTBLKSZ IS NOT USED FOR TWX TERMINALS 

1050 * CINTVL= NO. OF SECONDS BEFORE COMPUTER SHOULD CALL STATION 

1051 * — NOT NEEDEDTF NO AUTO CALL FEATURE 

1052 * Q) 

1053 T2 TERMINAL QBY=T f DCB=LNTWX, RLN=l f TERM=3335, QUEUES=MR, X 

DIALNO=NONE f ALTDEST=T2 

1076 * 

1077 * TPKOCES3 ENTRIES 

1078 * 

1079 * IN T3E FOLLOWING MACROS — 

1080 * PCB= NAME OF PROCESS CONTROL BLOCK — ALL TPROCESS 

1081 * ENTRIES FOR THE SAME APPLICATION PROGRAM MUST HAVE THE SAME 

1082 * PCB 

1083 * QUEUES= IS THE SAME AS FOR A TERMINAL MACRO — HOWEVER, BY 

1084 * OMITTING, USER SPECIFIES THAT THIS 2NTRY IS USED FOR PUTS 6 

1085 * WRITES FROM APPLICATION PROGRAM 

1086 * ALTDEST= FOR OUTPUT, GIVES WHERE REPLIES TO OPERATOR MSGS. SENT 

1087 * IF WERE FNTEPSD FROM AN APPLICATION PROGRAM — NOT APPLICABLE 

1088 * TO COBOL — 

1089 * ONLY NEEDED FOR INPUT QUEUES IF REUSABLE DISK QUEUEING 

1090 * RECDEL= SPECIFIES CHARACTER USED TO DENOTE END OF RECORD 

1091 * DATE=YES — THIS IS NEEDED FOR ALL INPUT TPROCESS ENTRIES 

1092 * FOR A COBOL PROGRAM. THIS WILL MAKE THE DATE AND TIME 

1093 * AVAILABLE SO IT MAY BE PLACED IN THE COBOL PROGRAM 

1094 * INPUT CD. 

1095 * 

1096 * INPUT TPROCESS ENTRY FOR COBOL PROGRAM RUNNING WITH TERMINALS 

1097 * 

1098 PIN TPROCESS PCB=PCBLK, QUEUES=MR, ALTDEST=PIN,RECDEL=FF,DATE=YES fa) 

1127 * 

1128 * OUTPUT TPROCESS ENTRY FOR COBOL PROGRAM RUNNING WITH TERMINALS 

1129 * 

1130 POUT TPROCESS PCB=PCBLK, RECDEL=FF 

1156 * 

1157 * THE FOLLOWING TWO INPUT TPROCESS ENTRIES ARE FOR COBOL PROGRAMS 

1158 * THAT SIMULATE TERMINAL INPUT DATA — USED FOR TESTING WITHOUT 

1159 * TERMINALS 

11.60....* - - - — - - - - - - - -/--v 

1161 PI TPROCESS PCB=PCBLK1,QUEUES=MR,ALTDEST=P1,RECDEL=FF,DATE=YES (jo) 

1187 * 

1188 P2 TPROCESS PCB=PCBLK1, QUEUES=MR, ALTDEST=P2,RECDEL=FF, DATE-YES (c) 

1214 * W 

1215 * OUTPUT TPROCESS ENTRY FOR THESE COBOL PROGRAMS 

1216 * 

1217 POUT1 TPROCESS PCB=PCBLK1,RECDEL=FF d 

1243 * 

1244 * THE FOLLOWING SIX INPUT TPROCESS ENTRIES ARE FOR COBOL QUEUE 

1245 * STRUCTURE TEST PROGRAMS 

1246 * 

1247 PQ1 TPROCESS PCB=PCBLK2, QUEUES=MR, ALTDEST=PQ1, RECDEL=FF, DATE=YES 

1273 * 

1274 PQ2 TPROCESS PCE==PCBLK2, OUEUES=MR, ALTDEST=PQ2, RECDEL=FF, DATE- YES (f) 
1300 * W 

Figure 114. A Message Control Program for Teleprocessing Applications (Part 7 cf 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT' 



F15OCT70 5/03/72 



© 



O 



1301 PQ3 

1327 * 

1328 PQ4 

1354 * 

1355 PQ5 
1381 * 



TPROCESS PCB=PCBLK2 t QUEUES=KR, ALTDEST=PQ3, RECDEL=FF, DATE=YES 
TPROCESS PCB=PCBLK2 , QUEOES=MR, ALTDEST=PQ4, RECDEL=FF r DATE=YES 
TPROCESS PCB=PCBLK2, QUEUES=MR, ALTDEST=PQ5, RECDEL=FF, DATE=YES 
TPROCESS PCB=PCBLK2 , QUEUES=MR, ALTDEST=PQ6 r RECDEL=FF, DATE=YES 
OUTPUT TPROCESS ENTRY FOR COBOL QUEUE STRUCTURE TEST PROGRAMS 
PCB=--PCELK2, RECDEL=FF 



1382 PQ6 
1408 * 
1409 
ltlO * 
1411 PQOUT 

1437 * 

1438 * 
1439 
1440 
1441 
1442 
1443 
1444 
1445 
1446 
1447 
1448 
1449 
1450 
1451 
1452 
1453 
1454 
1455 
1456 

1457 * 

1458 Dl 

1479 * 

1480 * 
1481 
1482 
1483 
1484 
1485 
1486 
1487 
1488 
1489 
1490 
1491 
1492 

1493 * 

1494 LIST1050 INVLIST ORDER=(Tl+6215) (a) 
1503 * 

1504 
1505 
1506 
1507 
1508 



TPROCESS 



DISTRIBUTION LIST ENTRY — 

IN THE FOLLOWING MACRO — 

LIST = NAMES OF TERMINAL OR TPROCESS ENTRIES IN TKE 
TERMINAL TABLE 

THE LIST SHOULD NOT INCLUDE A TPROCESS ENTRY FOR A 
COBOL APPLICATION PROGRAM 

TYPE= D SPECIFIES THIS IS A DISTRIBUTION LIST ENTRY 
C WOULD SPECIFY A CASCADE LIST ENTRY 

DISTRIBUTION LISTS INDICATE A MESSAGE FORWARDED TO THEM 
WILL BE SENT TO ALL NAMES IN THE LIST 

WITH CASCADE LISTS, MESSAGES WILL BE SENT TO THE QUEUE 
SPECIFIED IN THE LIST WITH THE FEWEST NO. OF MESSAGES 

1050 AND TWX — USED BY MESSAGE PROCESSING PROGRAM 



TLIST LIST=(T1,T2),TYPE=D (a) 



INVITATION LISTS 

SHOULD ALWAYS BE SPECIFIED FOLLOWING THE MACROS DEFINING THE TERMINAL 

TABLE 

LIST FOR 1050 LINE — 

ORDER= ENTRIES FOR STATIONS ON LINE IN THE ORDER TO BE POLLED 
Tl SPECIFIES A STATION ON THE LINE DEFINED BY A TERMINAL 

MACRO 
+ SPECIFIES THE TERMINAL IS INITIALLY ACTIVE, - WOULD 
SPECIFY IT WAS INITIALLY INACTIVE 
6215=A0 IN 1050 CODE — A IS THE STATION ADDRESS — ASKS FOR 
INPUT FROM ANY INPUT COMPONENT 



* LIST FOR TWX LINE — 

* SINCE A TERMINAL MACRO WITH UTERM=YES WAS DEFINED FOR THIS LINE, 

* THIS MACRO NAME IS USED RATHER THAN THE ONE FOR THE TWX STATION 
* 

* THIS IS A SWITCHED LINE WHICH DOES NOT HAVE THE AUTO-CALL FEATURE- 



PAGE 
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LOC OBJECT CODE 



ADDRl ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



0009DB 0C 

0009DC 01B151FFC3F343F3 



THE COMPUTER NEVER ASKS FOR THE ID SEQUENCE FROM THE TWX TERMINAL 
UNLESS THE AUTO-CALL FEATURE IS PRESENT 

IF AUTO-CALL FEATURE IS NOT PRESENT OR TWX TERMINAL DOES NOT HAVE 
AN ID SEQUENCE FOR AN ANSWER-BACK, OMIT THE ID SEQUENCE CHARS. IN 
THE INVLIST MACRO 

IF AN ID SEQUENCE IS USED FOR THE TWX — IT IS SUGGESTED THE 
FOLLOWING CHARACTERS BE USED — CR LF IDCHARS CR LF XON — IN LINE 
CODE 



1509 
1510 
1511 
1512 
1513 
1514 
1515 
1516 
1517 
1518 
1519 
1520 
1521 

1522 * 

1523 LISTTWX INVLIST ORDER=(T2A+) , CPUID=TWXSEQ (b) 

1532 * ^S 

1533 * REFERENCED BY LISTTWX AS CPUID OPERAND 

1534 * — SUGGESTED USE NULL CR LF RUBOUT IDCHARS CR LF XON 

1535 * CPUID IS — COBOL 

1536 TWXSEQ DC X'OC 12 CHARACTERS 

1537 DC X*01B151FFC3F343F333B15189' 

1538 * 



THE CPUID OPERAND IS NEEDED FOR TWX TERMINALS- 
TERMINAL WHEN CONNECTION IS MADE 



-IT WILL PRINT AT 



Figure 114. A Message Control Program for Teleprocessing Applications (Part 8 of 20) 
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PAGE 11 

LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15CCT70 5/03/72 

1540 **** 

1541 * 

1542 * MESSAGE HANDLERS — MH'S 

1543 * 

1544 * THE HEADER RECEIVED FROM THE TERMINAL IS — 

1545 * POSSIBLE LINE FORMAT CHARS. — CR, LF, NL 

1546 * $ 

1547 * BLANK 

1548 * MSGTYPE — 1 CHAR. 

1549 * BLANK 

1550 * SOURCE — 2 CHARS. 

1551 * BLANK 

1552 * EOF FIELD — F IF END OF A GROUP OF MESSAGES 

1553 * — ANY OTHER CHAR. (EXCEPT BLANK) IF NOT 

1554 * BLANK 

1555 * ACTION CODE FOR APPLICATION PROGRAM — 2 CHARS. 

1556 * BLANK 

1557 * PUNCTUATION MARK — PERIOD 

1558 * 

1559 **** 

1560 *** 

1561 * 

1562 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO 1050 TERMINAL 

1563 * 

1564 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

1565 * LC= IS THE ONLY REQUIRED OPERAND — 

1566 * OUT SAYS TO REMOVE LINE CONTROL CHARS. 

1567 * IN SAYS NOT TO REMOVE LINE CONTROL CHARS. 

1568 * STOP= SAYS WHEN EOB ERROR FOUND AND RETRY COUNT EXHAUSTED, 

1569 * ONLY THAT PORTION OF MESSAGE RECEIVED OR SENT CONTINUES 

1570 * THRU MH — USER MAY CHECK ERROR RECORD BITS IN INMSG OR OUTMSG 

1571 * CONT= SAYS THAT AFTER RETRY, SET BIT IN ERROR RECORD — BUT 

1572 * CONTINUE TRANSMISSION 

1573 * IF NEITHER STOP NOR CONT SPECIFIED, NO EOB CHECKING PERFORMED 

1574 * 

QJ) 1575 MH1050 STARTMH LC=OUT, CONT=YES 

1596 * 

1597 * THE FOLLOWING MACRO IS REQUIRED AS THE FIRST MACRO IN ANY INCOMING 

1598 * GROUP 

WM 1599 INHDR 

1613 * 

1614 * THE FOLLOWING MACRO TRANSLATES FROM LINE CODE TO EBCDIC — MACROS 

1615 * FOLLOWING THIS WILL ACT UPON CHARACTERS IN EBCDIC — IT WILL CAUSE 
^ 1616 * ENTIRE xMESSAGE TO BE TRANSLATED EVEN THOUGH IN INHDR GROUP 

Q5) 1617 CODE 

1641 * 

1642 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

r\ 1643 * 

(16) 1644 LOG MSGLOG 

1655 * 

®1656 * SET SCAN POINTER TO $ 
1657 SETSCAN C'$' 

1673 * 

1674 * PROCESS THE REMAINDER OF THE HEADER ACCORDING TO THE MSGTYPE FIELD 

1675 * SPECIFIED NEXT IN THE HEADER — IF THE NEXT FIELD MATCHES THE CHARACTER 

Figure 114. A. Message Control Program for Teleprocessing Applications (Part 9 of 20) 
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LOC OBJECT CODS ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

1676 * SPECIFIED IN THE OPERAND, THE MACROS SPECIFIED BETWEEN IT AND THE 

1677 * NEXT MSGTYPE MACRO ARE EXECUTED AND CONTROL IS THEN PASSFD TO THE 

1678 * NEXT DELIMITER — IN THIS CASE INBUF -IF THEY DO NOT MATCH, CONTROL 

1679 * PASSES TO THE NEXT MSGTYPE MACRO WHERE THE TEST IS AGAIN MADE 

1680 * 

(18) 1681 * IF MSGTYPE IS 1, THIS MESSAGE SHOULD BE FORWARDED TO Th*. 1.0-50 
v 1682 MSGTYPE C'l' 

1698 * 

1699 * SCAN POINTER IS AT SOURCE FIELD — SINCE THIS IS A NON-SWITCHED STATION 

1700 * — ORIGIN VERIFIES THAT THE SOURCE FIELD CONTAINS THE SYMBOLIC NAME 

1701 * OF THE STATION THAT WAS INVITED TO SEND THE MESSAGE — IF NOT, ERROR 

O1702 * BIT IN ERROR RECORD FOR MESSAGE IS SET TO 1 
1703 ORIGIN 

1716 FORWARD D£ST=C , T1* 

1734 * 

1735 * IF MSGTYPE IS 2, THIS MESSAGE SHOULD BE FORWARDED TO TWX TERMINAL— 

1736 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

1737 MSGTYPE C'2' 
1755 ORIGIN 

1765 FORWARD DEST=C ' T 2 * 

1780 * 

1781 * IF MSGTYPE IS 5, THIS MESSAGE SHOULD BE FORWARDED TO THE COBOL 

1782 * APPLICATION PROGRAM — 

1783 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

1784 MSGTYPE C*5* 
1802 ORIGIN 

1812 FORWARD DEST=C PIN" 

1827 * 

1828 * IF MSGTYPE IS 6, THE SOURCE FIELD HAS BEEN OMITTED — UNNECESSARY TO 

1829 * ISSUE AN ORIGIN FOR A NON-SWITCHED LINE — SEND MESSAGE TO THE COBOL 

1830 * APPLICATION PROGRAM 

1831 MSGTYPE C'6' 

1849 FORWARD DEST=C PIN' 

1864 * 

1865 * IF THE MSGTYPE IS ANYTHING ELSE, IT IS INVALID — SET THE USER ERROR 

1866 * BIT WITH THE TERRSET MACRO — IN THE INMSG GROUP, WE WILL CANCEL MSG. — 

1867 * ISSUE FORWARD MACRO ANYWAY SINCE REQUIRED 

1868 MSGTYPE 

@1873 FORWARD DEST=C'T1' 

1888 TERRSET 

1895 * 

1896 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

@1897 * OF THE MESSAGE 
1898 INBUF 

1903 * 

1904 * SPECIFY THE MAXIMUM NO. OF CHARACTERS ALLOWED IN AN INCOMING MESSAGE 

1905 * — THIS MACRO ALSO CHECKS IF THE INPUT BUFFER IS FILLED WITH IDENTICAL 

1906 * CHARACTERS, USUALLY AN INDICATION OF STATION MALFUNCTION — SETS A 
^-. 1907 * BIT IN ERROR RECORD FOR EITHER CONDITION 

^3) 1908 CUTOFF 900 

1919 * 

1920 * INSERT X'FF* FOR EVERY NL AND LF CHARACTER — X'FF' IS THE RECDEL CHAR. 

1921 * SPECIFIED IN THE TPROCESS MACROS — IF A MESSAGE WERE ALWAYS BEING 

1922 * FORWARDED TO AN APPLICATION PROGRAM, WE COULD USE DELIMIT INSTEAD 

1923 * OF XLl'FF' 

Figure 11U. A. Message Control Program for Teleprocessing Applications (Part 10 of 20 J 
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LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

(24^ 1924 MSGEDIT { <RA, XLl'FF' ,XL1' 15' ) , (RA, XL1" FF' , XL1' 25' ) ) 

^- / 1953 * 

1954 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS — IT IS EXECUTED 

1955 * AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN PROCESSED — NO EXECUTABLE 

©1956 * USER- WRITTEN CODE SHOULD BE INCLUDED IN THIS SUBGROUP 
1957 INMSG 

1965 * 

1966 * CANCELMG CAUSES IMMEDIATE CANCELLATION OF MESSAGE IF ANY ERRORS 

1967 * SPECIFIED BY ITS MASK OCCUR — IF USED, IT MUST BE 1ST MACRO UNDER 

1968 * INMSG — AN ERRORMSG MACRO MAY THEN NOTIFY OF THE ERROR — 

1969 * CANCELMG IF THE USER ERROR BIT IS SET INDICATING THE MSGTYPE FIELD 

@1970 * WAS INVALID — BIT20 
1971 CANCELMG X'0000080000' 

1979 * 

1980 * If? THE FOLLOWING ERROR MESSAGES. THE 1ST FIELD IS THE MASK CORRE- 

1981 * SPONDING TO THE BITS IN THE ERROR RECORD, DE3T= IS ALWAYS Tl FOR THE 

1982 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

1983 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 

1984 * ERROR MESSAGE 

1985 * 

1986 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

©1987 * RETURNED WITH A LINE FEED AT THE END OF TEE PRINTING OF THE MESSAGE 
1988 ERRORMSG X' 8000000000' ,DEST=C'Tl* , X 

DATA=C'E ERROR IN PROCESSING HEADER ' 
2004 ERRORMSG X' 4000000000' ,DEST=C'T1' , X 

DATA=C*E INVALID ORIGIN IN HEADER ' 
2016 ERRORMSG X* 0200000000' ,DEST=C'T1' , X 

DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ' 
2028 ERRORMSG X" 0100000000* ,DEST=C'T1'' , X 

DATA=C'E MESSAGE TOO LONG • 

2040 * 

2041 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

2042 * QUEUEING WITH OR WITHOUT DISK BACKUP 

2043 ERRORMSG X* 0040000000' ,DEST=C'Tl' , X 

DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN * 

2055 * 

2056 ERRORMSG X' 0002000000' , DEST=C Tl' , X 

DATA=C'E FORWARDED TO INVALID DESTINATION ' 
2-06&- ERRORMSG X , .0.Qaa4Q.QQQQ'.,DES.T=C'_Tl , . J X 

DATA=C'E INVALID STATION ID AT CONNECT TIME ' 
2080 1TRRORMSG X' 0000200000' ,DEST=C'T1' , X 

DATA=C*E TERMINAL IS IN HOLD STATUS ' 
2092 ERRORMSG X' 0000080000" ,DEST=C'T1' , X 

DATA=C'E MSGTYPE CODE IN HEADER INVALID ' 
2104 ERRORMSG X' OOOOOOEOOO' , DEST=C'T1' , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED • 
2116 * 
^ 2117 * INEND IS REQUIRED AS LAST DELIMITER MACRO OF INCOMING GROUP 
y2& 2118 INEND 

2122 * 

2123 *** 

2124 * 

@2125 * OUTGOING GROUP OF MESSAGE HANDLER FOR 1050 TERMINAL 
2126 OUTHDR 

Figure 114. A Message Control Program for Teleprocessing Applications (Part 11 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

2132 * 

2133 * THE FOLLOWING MACRO CAUSES EOT LINE CONTROL CHARACTERS TO BE INSERTED 

2134 * IN EACH OUTGOING MESSAGE — SINCE NTBLKSZ= (BLKSIZE) CODED IN THE 

2135 * TERMINAL MACRO — IT ALSO INSERTS EOB CHARS. — THIS PARAMETER COULD 

2136 * ALSO BE PLACED AS AN OPERAND OF THIS MACRO TO OVERRIDE THE NO. 

2137 * SPECIFIED IN THE TERMINAL MACRO 

2138 MSGFORM 

2149 * 

2150 * SINCE ERROR MESSAGES ARE SENT TO THIS TERMINAL — AND THESE COULD 

2151 * INCLUDE THOSE FOR THE APPLICATION TO APPLICATION PROGRAM WHICH 

2152 * WILL NOT HAVE A HEADER AND CANNOT BE PROCESSED AS A NORMAL OUTPUT 

2153 * MESSAGE TO THIS TERMINAL — CHECK 1ST CHARACTER FOR AN E — THE 1ST 

2154 * CHAR. OF EVERY ERRORMSG — IF NOT E WILL SKIP TO NEXT MSGTYPE MACRO— 

2155 * IF E r WILL PROCESS TO NEXT MSGTYPE MACRO AND THEN SKIP TC NEXT 

2156 * DELIMITER — OUTBUF 

2157 MSGTYPE C'E* 

2173 * 

2174 * SET SCAN POINTER BACK TO BEGINNING OF BUFFER AND INSERT NL CHARACTER 

2175 * AT BEGINNING OF MESSAGE — IDLES WILL BE INSERTED AFTER NL IN OUTBUF 

2176 SETSCAN 1, POINT=BACK 
2187 MSGEDIT ( (I,XL1' 15' ,SCAN) ) 

2202 * 

2203 * USE MSGTYPE WITH BLANK OPERAND TO PROCESS OTHER MESSAGES 

2204 MSGTYPE 

2209 * 

2210 * INSERT NL CHARACTER AT BEGINNING OF MESSAGE — IDLES WILL BE INSERTED 

2211 * AFTER NL IN OUTBUF 

2212 MSGEDIT ( (I, XLl'15* , SCAN) > 

2224 * 

2225 * SET THE SCAN POINTER TO THE PERIOD IN THE HEADER AND INSERT DATE, 

2226 * TIME, AND SEQUENCE NO. — INSERTED IN EBCDIC SO DO BEFORE CODE 

2227 SETSCAN C. • 

2240 * 

2241 * IF NO OPERAND — BOTH DATE AND TIME ARE INSERTED — SPACE MUST BE 

2242 * RESERVED BY MEANS OF THE RESERVE= OPERAND OF DCB FOR LINE — THE DATE 

2243 * IS IN FORM — (BLANK) YY.DDD — 7 CHARS. — TIME IN FORM — 

@2244 * (BLANK) HH.MM.SS — 9 CHARACTERS 
2245 DATETIME 

2261 * 

2262 * SEQUENCE IN AN OUTBDR SUBGROUP INSERTS SEQUENCE NO. IN FORM — 

2263 * (BLANK) NNNN — 5 CHARS. — SPACE MUST BE RESERVED BY MEANS OF RESERVE= 

©2264 * OPERAND OF DCB FOR LINE 
2265 SEQUENCE 

2275 * 

2276 * LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND — PUT MACRO AFTER 

2277 * INSERTION OF DATE, TIME, AND SEQUENCE NOS. SO THESE WILL APPEAR 

2278 * IN LOGGEiJ HEADER 

2279 * 

2280 LOG MSGLOG 

2288 * 

2289 * THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 

©2290 * OF THE MESSAGE 
2291 OUTBUF 

2296 * 
2297 * INSERT NL CHAR. FOR EVERY X* FF' CHAR. IN MESSAGE — X' FF' IS THE 

Figure 114. A Message Control Program for Teleprocessing Applications (Part 12 of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

2298 * RECDEL CHAR. SPECIFIED IN THE TPROCESS MACROS 

2299 MSGEDIT ( <RA, XL1» 15' , XLl'FF' ) ) 

2317 * 

2318 * INSERT 13 IDLE CHARS. AFTER EVERY NL CHARACTER PLACED IN MESSAGE 

2319 MSGEDIT ( (I, (X' 17" ,13) , XL1' 15' ) ) 

2336 * 

2337 * TRANSLATE THE MESSAGE FROM EBCDIC TO LINE CODE — IF ISSUED IN A 

2338 * SUBGROUP AND ANY SFGMENTS OF A MESSAGE PROCESSED BY THAT SUBGROUP, 

2339 * THE ENTIRE MESSAGE IS TRANSLATED 

2340 CODE 

2349 * 

2350 * THE OUTMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN OUTGOING 

2351 * GROUP — IT IS EXECUTED ONLY AFTER AN ENTIRE BLOCK OR MESSAGE HAS BEEN 

2352 * SENT 

2353 OUTMSG 

2362 * 

2363 * THE HOLD MACRO SUSPENDS TRANSMISSION TO A STATION EITHER FOR A TIME 

2364 * INTERVAL (IF SPECIFIED) OR UNTIL RELEASED BY AN OPERATOR CONTROL 

2365 * MESSAGE — IF NOT USED, MESSAGES THAT CANNOT BE TRANSMITTED ARE 

2366 * TREATED AS THOUGH THEY HAVE BEEN TRANSMITTED — ALSO, A HOLD OPERATOR 

2367 * CONTROL MESSAGE HAS NO EFFECT IF THERE IS NO HOLD MACRO — 

2368 * BITS BEING TESTED BY MASK ARE FOR HARDWARE ERRORS 

2369 HOLD X' O0OO0OEOO0' 

2381 * 

2382 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

2383 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

2384 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

2385 * THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 

2386 * ERROR MESSAGE 

2387 * 

2388 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

2389 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

2390 ERRORMSG X' 8000000000' ,DEST=C Tl* , X 
DATA=C'E ERROR IN PROCESSING HEADER ■ 

2402 * 

2403 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

2404 * QUEUEING WITH OR WITHOUT DISK BACKUP 

2405 ERRORMSG X* 0040000000' f DEST=C'Tl' , X 
DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 

- --■- LOW DOWN ■ ' - - - - 

2417 * 

2418 ERRORMSG X' 0000400000' ,DEST=C'T1' , X 
DATA=C'E INVALID STATION ID AT CONNECT TIME ' 

2430 ERRORMSG X' 0000200000* ,DEST=C*T1' , X 

DATA=C*E TERMINAL IS IN HOLD STATUS ' 

2442 ERRORMSG X' 000000E000 1 ,DEST=C'T1' , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED • 

2454 * 

2455 * OUTEND REQUIRED AS LAST DELIMITER MACRO OF OUTGOING GROUP 

2456 OUTEND 

2460 * 

2461 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 

2462 * MORE THAN 1 MH 
000E60 2-463 LTORG 

2464 * 

Figure 114. A Message Control Program for Teleprocessing Applications (Part 13 of 20) 
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LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT F15OCT70 5/0 3/72 

2466 *** 

2467 * 

2468 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO TWX TERMINAL 

2469 * 

2470 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

OU"71_ * T r*= TO rnTIT QJJLY pT?r*TTTPTTr\ /-*pgX)7VTJTJ 

2472 * OUT SAYS TO REMOVE LINE CONTROL CHARS. 

2473 * IN SAYS NOT TO REMOVE LINE CONTROL CHARS. 

2474 * 

2475 MHTWX STARTMH LC=OUT 

2489 * 

2490 * THE FOLLOWING MACRO IS REQUIRED AS THE FIRST MACRO IN ANY INCOMING 

2491 * GROUP 

2492 INHDS 

2503 * 

2504 * THE FOLLOWING MACRO TRANSLATES FROM LINE CODE TO EBCDIC — MACROS 

2505 * FOLLOWING THIS WILL ACT UPON CHARACTERS IN EBCDIC — IT WILL CAUSE 

2506 * ENTIRE MESSAGE TO BE TRANSLATED EVEN THOUGH Itf INHDR GROUP 

2507 CODE 

2527 * 

2528 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

2529 * 

2530 LOG MSGLOG 

2538 * 

2539 * SET SCAN POINTER TO $ 

2540 SETSCAN C' $' 

2553 * 

2554 * PROCESS THE REMAINDER OF THE HEADER ACCORDING TO THE MSGTYPE FIELD 

2555 * SPECIFIED NEXT IN THE HEADER — IF THE NEXT FIELD MATCHES THE CHARACTER 

2556 * SPECIFIED IN THE OPERAND, THE MACROS SPECIFIED BETWEEN IT AND THE 

2557 * NEXT MSGTYPE MACRO ARE EXECUTED AND CONTROL IS THEN PASSED TO THE 

2558 * NEXT DELIMITER — IN THIS CASE INBUF -IF THEY DO NOT MATCH, CONTROL 

2559 * PASSES TO THE NEXT MSGTYPE MACRO WHERE THE TEST IS AGAIN MADE 

2560 * 

2561 * IF MSGTYPE IS 1, THIS MESSAGE SHOULD BE FORWARDED TO THE 1050 

2562 MSGTYPE C*l* 

2578 * 

2579 * SCAN POINTER IS AT SOURCE — ISSUE ORIGIN—SINCE THIS IS A SWITCHED 

2580 * LINE, ORIGIN WILL CHECK VALIDITY OF FIELD AND IDENTIFY THE CALLING 

2581 * STATION TO TCAM 

2582 ORIGIN 

2592 FORWARD DEST=C , T1' 

2607 * 

2608 * IF MSGTYPE IS 2, THIS MESSAGE SHOULD BE FORWARDED TO TWX TERMINAL— 

2609 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

2610 MSGTYPE C*2' 
2628 ORIGIN 

2638 FORWARD DEST=C'T2' 

2653 * 

2654 * IF MSGTYPE IS 5, THIS MESSAGE SHOULD BE FORWARDED TO THE COBOL 

2655 * APPLICATION PROGRAM — 

2656 * SEE COMMENTS UNDER MSGTYPE 1 FOR OTHER MACROS 

2657 MSGTYPE C'5' 
2675 ORIGIN 

2685 FORWARD DEST=C'PIN' 

Figure 114. A. Message Control Program for Teleprocessing Applications (Part 14 of 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



2700 
2701 
2702 
2703 
2704 
2705 
2723 
2738 
2739 
2740 
2741 
2742 
2747 
2762 
2769 
2770 
2771 
2772 
2777 
2778 
2779 
2780 
2781 
2782 
2790 
2791 
2792 
2793 
2794 
2795 
2818 
2819 
2820 
2821 
2822 
2830 
2831 
2832 
2833 
2834 
2835 
2836 
2841 
2842 
2843 
2844 
2845 
2846 
2847 
2848 
2849 
2850 

2862 



IF MSGTYPE IS 6, THE SOURCE FIELD HAS BEEN OMITTED (IN ORDER FOR 
THE COBOL PROGRAM TO CHECK THAT THE LINE NAME — T2A — RATHER THAN THE 
STATION NAME — T2 — IS GIVEN AS SOURCE) — THE MESSAGE IS TO BE SENT TO 
THE COBOL APPLICATION PROGRAM 

MSGTYPE C ' 6 ' 

FORWARD DEST=C* PIN' 

IF THE tfSGTYPE IS ANYTHING ELSE, IT IS INVALID — SET THE USER ERROR 
BIT WITH THE TERRSET MACRO — IN THE INMSG GROUP, WE WILL CANCEL MSG. — 
ISSUE FORWARD MACRO ANYWAY SINCE REQUIRED 

MSGTYPE 

FORWARD DEST=C'T1' 

TERRSET 

THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 
OF THE MESSAGE 
INBUF 

SPECIFY THE MAXIMUM NO. OF CHARACTERS ALLOWED IN AN INCOMING MESSAGE 
— THIS MACRO ALSO CHECKS IF THE INPUT BUFFER IS FILLED WITH IDENTICAL 
CHARACTERS, USUALLY AN INDICATION OF STATION MALFUNCTION — SETS A 
BIT IN ERROR RECORD FOR EITHER CONDITION 
CUTOFF 900 

DELETE EVERY CR CHAR. AND INSERT X* FF* FOR EVERY LF CHAR. — X' FF' 
IS THE RECDEL CHARACTER SPECIFIED IN THE TPROCESS MACROS (IF MESSAGES 
WERE ALWAYS GOING TO AN APPLICATION PROGRAM, WE COULD USE DELIMIT 
INSTEAD OF XLl'FF') 

MSGEDIT ( (RA, CONTRACT, XL1* 26* ) , (RA, XL1* FF' , XL1« 15» ) I 

THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS — IT IS EXECUTED 
AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN PROCESSED — NO EXECUTABLE 
USER-WRITTEN CODE SHOULD BE INCLUDED IN THIS SUBGROUP 

INMSG 
CANCELMG CAUSES IMMEDIATE CANCELLATION OF MESSAGE IF ANf ERRORS 

SPECIFIED BY ITS MASK OCCUR — IF USED, IT MUST BE 1ST MACRO UNDER 
INMSG — AN ERRORMSG MACRO MAY THEN NOTIFY OF THE ERROR — 
CANCELMG IF THE USER ERROR BIT I S SE T INDICATI NG T HE M S G TYPE FIELD 
WAS INVALID — BIT20 

CANCELMG X* 0000080000* 

IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 
SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 
1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 
THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 
ERROR MESSAGE 

THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 
RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

ERRORMSG X* 8000000000* ,DEST=C Tl* , X 

DATA=C'E ERROR IN PROCESSING HEADER * 
ERRORMSG X' 4000000000" ,DEST=C , T1' , X 

DATA=C*E INVALID ORIGIN IN HEADER * 



Figure 114. A. Message Control Program for Teleprocessing Applications (Part lb of 20) 
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LOC OBJECT CODE ADDR1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

2874 ERRORMSG X' 0200000000' ,DEST=C'T1' , X 

DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING i^SSAGE * 

2886 ERRORMSG X" 0100000000 ■ ,DEST=C'T1 ' , X 

DATA=C'E MESSAGE TOO LONG • 

2898 * 

2899 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

2900 * QUEUEING WITH OR WITHOUT DISK BACKUP 

2901 ERRORMSG X« 0040000000* f DEST=C , Tl' , X 

DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USFD-SX 
LOW DOWN • 

2913 * 

2914 ERRORMSG X* 0002000000' ,DEST=C Tl' , X 

DATA=C*E FORWARDED TO INVALID DESTINATION ' 
2926 ERRORMSG X" 0000400000' ,DEST=C'T1' , X 

DATA=C'E INVALID STATION ID AT CONNECT TIME ' 
2938 ERRORMSG X' 0000200000' , DEST=C'Tl' , X 

DATA=C E TERMINAL IS IN HOLD STATUS ' 
2950 ERRORMSG X' 0000080000' ,DEST=C'T1' , X 

DATA=C«E MSGTYPE CODE IN HEADER INVALID * 
2962 ERRORMSG X" O00000E000' , DEST=C'T1' , X 

DATA=C'E A HARDWARE ERROR HAS OCCURRED * 

2974 * 

2975 * INEND IS REQUIRED AS LAST DELIMITER MACRO OF INCOMING GROUP 

2976 INEND 

2980 * 

2981 *** 

2982 * 

2983 * OUTGOING GROUP OF MESSAGE HANDLER FOR TWX TERMINAL 
67) 2984 OUTHDR 

^-^ 2990 * 

2991 * INSERT CR LF RUBOUT AT BEGINNING OF MESSAGE 

2992 MSGEDIT ( (I, XL3' 261507' , SCAN) ) 

3004 * 

3005 * THE FOLLOWING MACRO CAUSES EOT LINE CONTROL CHARACTERS TO BE INSERTED 

3006 * IN EACH OUTGOING MESSAGE 

3007 MSGFORM 

3014 * 

3015 * SET THE SCAN POINTER TO THE PERIOD IN THE HEADER AND INSERT DATE, 

3016 * TIME, AND SEQUENCE NO. — INSERTED IN EBCDIC SO DO BEFORE CODE 

3017 SETSCAN C ' 

3030 * 

3031 * IF NO OPERAND — BOTH DATE AND TIME ARE INSERTED — SPACE MUST BE 

3032 * RESERVED BY MEANS OF THE RESERVE= OPERAND OF DCB FOR LINE — THE DATE 

3033 * IS IN FORM — (BLANK) YY. DDD — 7 CHARS. — TIME IN FORM — 

3034 * (BLANK) HH.MM.SS — 9 CHARACTERS 

3035 DATETIME 

3048 * 

3049 * SEQUENCE IN AN OUTHDR SUBGROUP INSERTS SEQUENCE NO. IN FORM — 

3050 * (BLANK) NNNN — 5 CHARS. — SPACE MUST BE RESERVED BY MEANS OF RESERVE^ 

3051 + OPERAND OF DCB FOR LINE 

3052 SEQUENCE 
3059 * 

30 60 * LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND— PUT MACRO AFTER 

3061 * INSERTION OF DATE, TIME, AND SEQUENCE NOS. SO THESE WILL APPEAR 

3062 * IN LOGGED HEADER 

Figure 114. A Message Control Program for Teleprocessing Applications (Part 16 of 20) 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



3063 
3064 
3072 
3073 
3074 
3075 
3079 
3080 
3081 
3082 
3100 
3101 
3102 
3103 
3104 
3113 
3114 
3115 
3116 
3117 
3126 
3127 
3128 
3129 
3130 
3131 
3132 
3133 
3139 
3140 
3141 
3142 
3143 
3144 
3145 
3146 
3147 
3148 

3160 
"3161 
3162 
3163 



3175 
3176 

3188 

3200 

3212 
3213 
3214 



LOG MSGLOG 

THE MACROS IN THE FOLLOWING SUBGROUP ARE EXECUTED FOR EVERY BUFFER 
OF THE MESSAGE 
OUTBUF 



INSERT CR LF RUBOUT FOR EVERY X* FF' CHAR. IN MESSAGE — X' FF' 
THE RFCDEL CHAR. SPECIFIED IN THE TPROCESS MACROS 
M3GEDIT ( (RA, XL3' 261507" , XL1" FF* ) ) 



IS 



TRANSLATE THE MESSAGE FROM EBCDIC TO LINE CODE — IF ISSUED IN A 
SUBGROUP AND ANY SEGMENTS OF A MESSAGE PROCESSED BY THAT SUBGROUP, 
THE ENTIRE MESSAGE IS TRANSLATED 
CODE 

THE OUTMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN OUTGOING 
GROUP — IT IS EXECUTED ONLY AFTER AN ENTIRE BLOCK OR MESSAGE HAS BEEN 
SENT 

OUTMSG 

THE HOLD MACRO SUSPENDS TRANSMISSION TO A STATION EITHER FOR A TIME 
INTERVAL (IF SPECIFIED) OR UNTIL RELEASED BY AN OPERATOR CONTROL 
MESSAGE — IF NOT USED, MESSAGES THAT CANNOT BE TRANSMITTED ARE 
TREATED AS THOUGH THEY HAVE BEEN TRANSMITTED — ALSO, A HOLD OPERATOR 
CONTROL MESSAGE HAS NO EFFECT IF THERE IS NO HOLD MACRO — 
BITS BEING TESTED BY MASK ARE FOR HARDWARE ERRORS 
HOLD X'OOOOOOEOOO" 

IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 
SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 
1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 
THE MESSAGE INCLUDES THE HEADER OF THE MESSAGE IN ERROR AND THE 
ERROR MESSAGE 

THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 
RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

ERRORMSG X* 8000000000* ,DEST=C"T1' , X 

DATA=C'E ERROR IN PROCESSING HEADER ' 

THE FOLLOWING "ERROR MESSAGE "SHOULD"ONLY OCCUR WITH MAIN STORAGE 
QUEUEING WITH OR WITHOUT DISK BACKUP 

ERRORMSG X' 0040000000' , DEST=C Tl" , X 

DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 

LOW DOWN • 



ERRORMSG X* 0000400000' ,DEST=C'T1" , 

DATA=C'E INVALID STATION ID AT CONNECT TIME ' 
ERRORMSG X" 0000200000" ,DEST=C'T1' , 

DATA=C'E TERMINAL IS IN HOLD STATUS • 
ERRORMSG X" 000000E000' ,DEST=C , T1' , 

DATA=C'E A HARDWARE ERROR HAS OCCURRED * 

OUTEND REQUIRED AS LAST DELIMITER MACRO OF OUTGOING GROUP 
OUTEND 
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LOC OBJECT CODE 



ADDR1 ADDR2 STMT SOURCE STATEMENT 



F15OCT70 5/03/72 



001270 



3218 * 

3219 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 

3220 * MORE THAN 1 MH 

3221 LTORG 

3222 * 



Figure 114. A. Message Control Program for Teleprocessing Applications (Part 17 of 20) 
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LCC OBJECT CODE ADDP1 ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

3224 *** 

3225 * 

3226 * MESSAGE HANDLER FOR INPUT FROM AND OUTPUT TO APPLICATION PROGRAM 

3227 * RUNNING WITH TERMINALS 

3228 * 

3229 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

3230 * LC= IS A REQUIRED OPERAND — PUT* IN* SINCE NO LINE CONTROL 

3231 * CHARACTERS TO REMOVE 

3232 MHTRMAPP STARTMH LC=IN 

3246 * 

3247 * THE INCOMING GROUP HANDLES MESSAGES COMING FROM AN APPLICATION 

3248 * PROGRAM — THE MESSAGES WILL SUBSEQUENTLY BE PROCESSED BY THE OUTGOING 

3249 * GROUP FOR THE DESTINATION TERMINAL 

3250 * 

@3251 * THE INHDR DELIMITER IS REQUIRED AND IS ALWAYS 1ST MACRO 
3252 INHDR 

3263 * 

3264 * LOG INCOMING HEADERS — USE DCBNAME AS OPERAND 

3265 * 

3266 LOG MSGLOG 

3274 * 

3275 * THE FORWARD MACRO IS REQUIRED IN EACH INHDR SUBGROUP — 

3276 * THE OPERAND DEST=PUT SAYS TO FORWARD TO THE DESTINATION SPECIFIED 

3277 * IN THE PREFIX TO THE APPLICATION PROGRAM WORK AREA 

3278 FORWARD DEST=PUT 

3286 * 

3287 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN AN INCOiMING 

3288 * GROUP — IT IS EXECUTED AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN 

3289 * PROCESSED 

3290 INMSG 

3298 * 

3299 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

3300 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

3301 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

3302 * 

3303 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

3304 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

3305 ERRORMSG X* 0200000000' ,DEST=C Tl' , X 

DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ■ 

3317 * 

3318 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

3319 * QUEUEING WITH OR WITHOUT DISK BACKUP 

3320 ERRORMSG X* 0040000000' ,DEST=C Tl* , X 

DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN ' : 
3332 ERRORMSG X' 0002000000' ,DEST=C'T1" , X 

DATA=C'E FORWARDED TO INVALID DESTINATION ' 

3344 * 

3345 * INEND IS REQUIRED AS LAST DELIMITER OF INCOMING GROUP 

3346 INEND 

3350 * 

3351 *** 
/ ~. 3352 * 

(39) 3353 * OUTGOING GROUP HANDLES MESSAGES BEING SENT TO APPLICATION PROGRAM 
3354 OUTHDR 

Figure 114. A. Message Control Program for Teleprocessing Applications (Part 18 of 20) 
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LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

3360 * 

3361 * DELETE ANY CHARS. SUCH AS CR,LF WHICH APPEAR BEFORE $ IN HEADER 

3362 MSGEDIT ( (R, CONTRACT, SCAN, C' $') ) 

3377 * 

3378 * SET SCAN POINTER OVER 2 NON-BLANK CHARS. — $ AND MSGTYPE FIELD — SO 

3379 * IT POINTS TO BEFORE SOURCE FIELD 

3380 SETSCAN 2 

3388 * 

3389 * INSERT SEQUENCE NO. — FORMAT IS (BLANK) NNNN — 5 CHARS — SPACE MUST BF 

3390 * RESERVED BY MEANS OF RESERVE= OPERAND OF DCB FOR LINE 

3391 SEQUENCE 

3398 * 

3399 * LOG OUTGOING HEADERS — USE DCBNAME AS OPERAND — PUT MACRO AFTER 

3400 * INSERTION OF SEQUENCE NO. SO THIS WILL APPEAR IN LOGGED HEADER 

3401 * 

3402 LOG MSGLOG 

3410 * 

3411 * SET SCAN POINTER OVER 2 NON- BLANK CHARS. (SOURCE FIELD) SO IT POINTS 

3412 * TO EOF FIELD 

3413 SETSCAN 2 

3421 * 

3422 * SETEOF IS USED TO IDENTIFY THE LAST MESSAGE OF A GROUP OF MESSAGES 

3423 * TO THE APPLICATION PROGRAM — IT CAUSES THE NEXT READ/CHECK AFTER 

3424 * THIS COMPLETE MESSAGE HAS BEEN RECEIVED TO PASS TO AN APPLICATION 

3425 * PROGRAM EODAD ROUTINE — (THE COBOL PROGRAM WOULD RECEIVE AN ETI 

3426 * INDICATION) 

3427 SETEOF C'F' 

3444 * 

3445 * NO OUTMSG SUBGROUP WILL BE EXECUTED FOR A MESSAGE BEING TRANSFERRED 

3446 * FROM A TPROCESS QUEUE TO AN APPLICATION PROGRAM — 

3447 * SO OMIT OUTMSG IN THIS MESSAGE HANDLER 

3448 * 

3449 * 

3450 * OUTEND IS REQUIRED AS LAST DELIMITER OF OUTGOING GROUP 

3451 OUTEND 

3462 * 

3463 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF KCP HAS 

3464 * MORE THAN 1 MH 
001390 3465 LTORG 

- 3466 * 



Figure 114. A. Message Control Program for Teleprocessing Applications (Part 19 of 20 ; 
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LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

3468 *** 

3469 * 

3470 * MESSAGE HANDLER FOR COBOL PROGRAMS THAT SIMULATE TERMINAL INPUT DATA 

3471 * — USED FOR TESTING WITHOUT TERMINALS 

3472 * 

3473 * THE FOLLOWING MACRO IS REQUIRED AND MUST BE FIRST 

3474 * LC= IS A REQUIRED OPERAND — PUT' IN* SINCE NO LINE CONTROL 

3475 * CHARACTERS TO REMOVE 

3476 MHAPPAPP STARTMH LC=IN 

3490 * THE INCOMING GROUP HANDLES MESSAGES COMING FROM AN APPLICATION 

3491 * PROGRAM — THE MESSAGES WILL SUBSEQUENTLY BE PROCESSED BY THE OUTGOING 

3492 * GROUP WHEN THE APPLICATION PROGRAM READS THEM BACK 

3493 * 

._. 3494 * THE INHDR DELIMITER IS REQUIRED AND IS ALWAYS 1ST MACRO 
(40) 3495 INHDR 

3506 * 

3507 * THE FORWARD MACRO IS REQUIRED IN EACH INHDR SUBGROUP — 

3508 * THE OPERAND DEST=PUT SAYS TO FORWARD TO THE DESTINATION SPECIFIED 

3509 * IN THE PREFIX TO THE APPLICATION PROGRAM WORK AREA 

3510 FORWARD DEST=PUT 

3518 * 

3519 * THE INMSG SUBGROUP IS SPECIFIED AFTER OTHER SUBGROUPS IN AN INCOMING 

3520 * GROUP — IT IS EXECUTED AFTER AN ENTIRE MESSAGE OR BLOCK HAS BEEN 

3521 * PROCESSED 

3522 INMSG 

3530 * 

3531 * IN THE FOLLOWING ERROR MESSAGES, THE 1ST FIELD IS THE MASK CORRE- 

3532 * SPONDING TO THE BITS IN THE ERROR RECORD, DEST= IS ALWAYS Tl FOR THE 

3533 * 1050 TERMINAL AND THE DATA= IS THE ERROR MESSAGE THAT IS SENT — 

3534 * 

3535 * THE LAST CHARACTER OF THE MESSAGE IS NL — SO THE CARRIAGE WILL BE 

3536 * RETURNED WITH A LINE FEED AT THE END OF THE PRINTING OF THE MESSAGE 

3537 ERRORMSG X' 0200000000' , DEST=C' Tl' , X 

DATA=C'E INSUFFICIENT BUFFERS FOR INCOMING MESSAGE ' 

3549 * 

3550 * THE FOLLOWING ERROR MESSAGE SHOULD ONLY OCCUR WITH MAIN STORAGE 

3551 * QUEUEING WITH OR WITHOUT DISK BACKUP 

3552 ERRORMSG X' 0040000000' , DEST=C'T1' , J, 

DATA=C'E PERCENTAGE OF BUFFER UNITS IN BUFMAX ARE USED-SX 
LOW DOWN ' 
3564 ERRORMSG X' 0002000000' , DEST=C'T1* , X 

DATA=C'E FORWARDED TO INVALID DESTINATION « 

3576 * 

3577 * INEND IS REQUIRED AS LAST DELIMITER OF INCOMING GROUP 

3578 INEND 

3582 * 

3583 *** 

3584 * 

3585 * OUTGOING GROUP HANDLES MESSAGES BEING SENT TO APPLICATION PROGRAM 

3586 * 

3587 * NO OUTMSG SUBGROUP WILL BE EXECUTED FOR A MESSAGE BEING TRANSFERRED 

3588 * FROM A TPROCESS QUEUE TO AN APPLICATION PROGRAM — 

3589 * SO OMIT OUTMSG IN THIS MESSAGE HANDLER 

3590 * 

3591 * 

PAGE 24 

LOC OBJECT CODE ADDRl ADDR2 STMT SOURCE STATEMENT F15OCT70 5/03/72 

3592 * OUTEND IS REQUIRED AS LAST DELIMITER OF OUTGOING GROUP 

3593 OUTEND 

3604 * 

3605 * A LTORG SHOULD BE CODED AFTER LAST DELIMITER OF EACH MH IF MCP HAS 

3606 * MORE THAN 1 MH 
001420 3607 LTORG 

3608 * 

3609 END 

Figure 114. A. Message Control Program for Teleprocessing Applications (Part 20 of 20) 
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Defini ng the B uffers 



User-defined areas of main storage 
receive any and all messages entering a 
TCAM network. Such areas, known as 
buffers, are used for handling, queueing, 
and transferring message segments between 
all lines and queueing media, and between 
queueing media and COBOL work areas. 



understand how the buffers 

is necessary to distinguish 
units and buffers. TCAM has 

pool that contains buffer 
ze. Buffer units are the 
blocks from which buffers 

(that is, buffer units are 

to form buffers). 

though the buffers for line 
the application program may 

each size specified should 
f the size specified for a 

order to use space 



In order to 
are defined, it 
between buffer 
one buffer unit 
units of one si 
basic building 
are constructed 
linked together 
Therefore, even 
groups and for 
differ in size, 
be a multiple o 
buffer unit, in 
optimally. 

Three operands of the INTRO macro, (l) , 
descrioe the TCAM buffer unit pool. As in 
the sample program shown in Figure 114, 
the operands that define the size of buffer 
units and specify the number assigned are 
KEYLEN, LNUNITS, and MSUNITS. The operands 
BUF-SI ZE , BUFI-N, and SU-FQ4JT r -given— in the 
DCB for line groups, (7c) , and in the PCB, 

{6 J, for an application program, specify 
the buffer size and the number of buffers 
to be assigned initially for a receiving or 
sending operation. The manner in which the 
PCI= operand of the DCB for a line group, 

uc\ . is coded greatly affects the number 
cbtfed for LNUNITS in the INTRO macro and 
the numbers coded for the BUFIN and BUFOUT 
operands of the DCB for the line group. 



Activating and Deactivating the Message 
Control Program 



The TCAM message control program is 
assembled, link-edited, and executed like 
any other program running under an OS 
system. The macros INTRO, OPEN, and READY, 
issued as a group, make up the data-set 
initialization and activation section of 
the message control program. 

Orderly deactivation of the TCAM system 
must stop incoming and outgoing message 
traffic and create a checkpoint record. 
The user must ensure that the data sets for 
any application program using TCAM as its 
access method are closed before the MCP 
enters its deactivation section, which 
closes the MCP data sets. (It is suggested 
that the headers of messages transmitted to 
the COBOL programs contain a code that 



signals the COBOL program to go to the 
STOPRUN statement. ) Finally, the wcp 
coding must return control to the OS 
supervisor. 

INTRO Macro ; As the first macro executed 
in the message control program, INTRO, 1 
establishes standard entry linkage, chains 
save areas, provides addressability, and 
saves the start parameter list pointer. (A 
description of the operands in the INTRO 
macro precedes the macro itself in the 
sample program. ) 

Note: The message below is issued if at 
least one of the following operands is 
omitted from the INTRO macro: STARTUP=, 
KEYLEN=, LNUNITS= , and (if DISK=YES is 
coded in the INTRO macro) CPB=. 



00 IED002A SPECIFY TCAM PARAMETERS 



The user may then enter the additional 
required parameters, changing certain other 
operands as desired. 

0£EN_Macro: The OPEN macros, \2j, complete 
the initialization of the TCAM data sets 
and activate tnem for use. The TCAM data 
sets that must be activated in the MCP by 

OPEN-macros are those .for -the -message 

queues, (a), checkpoint, optionally^bj, the 
line gronpSjM (c\ and the message logf 
optionally/ap^ If a snap dump is used, the 
user must airso open the data set for snap, 
e 
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READY Ma cr o: The READY macro , (V), must be 
the last instruction in the initialization 
and activation section of the MCP. When 
READY has executed, the system is ready to 
handle message traffic. 

CLOSE Macro : An optional snap dump of the 
program begins the deactivation section. 
Then the first CLOSE macro instruction, 
MM , is executed. This deactivation 
section is not executed until all data sets 
in TCAM application programs have been 
closed. In the example, the user closes 
the line group data sets, fa\ first; next 
the snap data £M£t» Cb) i then the message 
log data set, fcj ; the checkpoint data set 
next to last- (§) J and finally the message 
queues data set~r (^V 

Note: The data sets may be closed in any 
order provided that the checkpoint data set 
and the message queues data set are closed 
in the order indicated. 

RETURN_Macr o : The assembler-language Load 
instruction is issued to restore register 
13 with the address of the system save 
area, and the RETURN macro, (IT), is issued 
to return control to the OS stTpervisor. 
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Defining the MCP Data Sets arid Process 
Control Blocks 



The user must provide information that 
serves as an interface between the message 
control program and the application 
program. This information is contained in 
process control blocks (PCB) and is 
generated by the PCB macro. 

The message control program must also 
describe the MCP data sets to be used. Two 
of the four possible types of data sets 
usually required by every message control 
program are the line group data set, if 
there are lines, and the message queues 
data set, if there are disk queues. The 
operation of the MCP requires that either a 
message queues data set or a line group 
data set be opened. A user employing main 
storage queueing for application-to- 
application program processing (who, 
therefore, does not need either of tnese 
data sets) must, nevertheless, open a dummy 
line to meet this requirement. An error 
message will be issued at the system 
console because no hardware is attached, 
but this message can be ignored. 

If the user does not open a line and, 
therefore, does not need either a DCB for a 
line group or a TERMINAL entry, the 
assembly of the MCP, nevertheless, 
generates an error message for the 
undefined symbol of IEDQ3TCS. The user can 
either define this symbol in this program 
with a dummy label or ignore the severity 
level of 8 in the link-edit step. The 
symbol IEDQSTCS need not be correctly 
defined when the user is running only 
application-to-application programs. 

Either or both of the other two types of 
data sets — the checkpoint data set and 
the log data set -- may be specified if 
needed. To describe data sets to the 
system, the user (via a DCB macro) defines 
a data control block (DCB) for each data 
set cited. 

P CB_ Mac ro: A process control block, 
created through specification of the PCB 
macro, is required in the MCP for each 
active application program. The PCB macro 
is similar to the DCB for the line groups 
in that it specifies the name of the 
message handler to be used for messages 
being sent by or received from an 
application program, as well as buffer 
requirements. The TPROCESS macro (see the 
discussion under "Defining Terminal and 
Line Control Areas") refers to the name of 
the PCB macro. 

In the sample program given in Figure 
114 arethree process control blocks — 
PCBLK, (aji for a COBOL program running 



with terminals; PCBLKl, (b) , for COBOL 
programs that simulate the sending of 
messages from a remote terminal; and 
PCBLK2, (cY for testing COBOL programs 
that take~"advantage of the queue structure 
feature. Having these three control blocks 
makes it possiole for the COBOL program 
running with terminals to run at the same 
time as one of the other COBOL programs. 
In the example in this cnapter, the TE3TIP1 
program simulates a terminal sending 
messages to the TESTTP2 program. 

DCB_Macro: A data control block, created 
through specification of the DCB macro, 
(jj, is required for each data set referred 
to by the MCP. In the sample message 
control program, data control blocks are 
defined as follows: 

• The message queues DCB macro, which 
defines a data control block for a 
message queues data set, M5GQ (&")• 

• The checkpoint DCB macro, which defines 
a checkpoint data set if the checkpoint 
facility is to be used, CHKPT (bY 

• The line group DCB macro, which defines 
a line group data set, must be 
specified for each line group in the 
system. In the sample MCP, two line 
group data sets are defined — the 1050 
line group, named LN1050 (c), and the 



TWX line group, named Lt 






• The log DCB marco, which defines data 
sets for messages or message segments, 
should be specified for each secondary 
storage device on which messages or 
message segments may be logged. In the 
sample program, only one log DCB 
defining the MSGLOG data set, (e\ is 
specified. ^^ 

• The snap dump DCB macro, which defines 
the data set for a snap dump, should be 
specified only if the user wants a snap 
dump. In the sample program, the DUMP 
data set is defined, 



.e pro 



Defining T erm inal and Lin eControl kreas 



In writing an MCP, the user must provide 
information that identifies the remote 
stations, specifies their characteristics 
to the system, and tells how they are to be 
handled. Line control is the scheme of 
operating procedures and signals by which a 
teleprocessing system is controlled. 

Line control concerns itself with such 
tasks as establishing contact between a 
sending and a receiving station, directing 
a message to a specific station on a 
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multistation line, handling priorities when 
two stations try to send at the same time, 
and performing a user-specified action when 
a station fails to respond to a message. 

Several TCAM macros are available to the 
user for identifying stations and 
specifying how message transmission is to 
be handled. The TCAM macros used in the 
sample message control program given in 
Figure 113 — TTABLE, TERMINAL, INVLIST, 
TLIST, and TPROCESS — are described below. 
Two additional macros — OPTION, which 
reserves space for an option field, and 
LOGTYPE, needed only for logging entire 
messages — are also available to the COBOL 
user. 



TTABLE Macro : The TTABLE macro, (8) , 
defines the start and the end of tne 
terminal table, needed to provide 
information about each station and 
application program. 

TERMINAL Macro : The TERMINAL macro, (?), 
specified three times in the sample 
program, must be coded for each station 
that can accept messages (as well as for 
some terminals that can only enter 
messages), each group of non-switched 
terminals equipped with the hardware 
group-code" feature," arid each switched line 
to stations that do not uniquely identify 
themselves after calling the computer. 

Specification of the TERMINAL macro 
places a station or line name and 
associated information in this terminal 
table. TERMINAL produces a single entry- a 
group entry, or a line entry. In the 
example, the Tl entry, (aj , provides 
information about the 1050 terminal, the 
T2A entry, (b) , information about the^^ 
switched TWXiine, and the T2 entry, (cf) , 
information about the TWX terminal on this 
line. 

Note s: 

1. The "UTERM=YES" specification in the 
TERMINAL macro for the switched TWX 
line creates an entry for the line. 
This gives the program the control 
information it needs to handle 
stations that call this line. After 
the station is identified by means of 
the ORIGIN macro in the MH, the 
program then refers to the TERMINAL 
entry for the station. 

2. All TERMINAL macros for lines in a 
line group must be arranged in 
ascending relative line numbers. The 
TERMINAL macro for a particular line 
must immediately precede all TERMINAL 
macros for stations on that line. In 
the sample MCP, there is only one line 



per line group and one terminal per 
line, but this need not be true. 

TPROCE SS Ma cro: By placing the name of a 
queue for an application program, as well 
as associated information, in the terminal 
table, the TPROCESS macro, (T5) , helps 
connect a COBOL program with^the message 
control program. 

The user must specify one TPROCESS macro 
for each destination queue from which a 
COBOL program is to receive messages and at 
least one that is used when messaaes are 
sent by a COBOL program. (That is, one 
output TPROCESS entry is required for each 
application program running 

simultaneously. ) The output TPROCESS entry 
is not the name of a queue. In the sample 
program, for example, twelve TPROCESS 
entries are specified. The PIN entry, 
, identifies an input destination queue 
a COBOL program running with terminals; 
POUT identifies an output process entry. 

Similarly, the PI, (c) , and P2, (T) , 
entries identify inpHt destination queues 
for COBOL programs tnat simulate terminal 
input data, and the POUTl, (e) , entry 
identifies an output process-gentry for such 
COBOL programs. The PQl, PQ2, PQ3, PQ4, 
PQ5, PQ6, and PQOUT TPROCESS entries are 

used— for -COBOL -programs that employ- -the 

queue structure feature. 

Note: Because the PIN and POUT entries in 
the example refer to one process control 
block (PCBBLK) and the Pi, P2, and POUri 
entries refer to another process control 
block (PCBBLKl), a program running with 
terminals can run concurrently with another 
program. This is alco true of the PQ 
entries, which refer to PCBLK2. 

TLIST Macro: An instruction that places 
the name of a list of a single, a group, or 
a process entry in the terminal table, the 
TLIST macro, (irj , must be specified for 
each such listHio be created. This list 
can be specified as either a distribution 
list or a cascade list. When a message is 
sent to a distribution list, the same 
message is sent to all locations on the 
list. When a message is sent to a cascade 
list, the message is transmitted to the 
listed destination with the fewest messages 
enqueued. In the sample message control 
program, the TLIST entry Dl, <a>, 
represents a distribution list entry. The 
list should not include a TPROCESS entry 
for a COBOL application program. 

INVLIST Mac ro: An instruction that creates 
an invitation list entry containing the 
invitation characters for the stations on 
the line (in the order in which they are to 
be invited to send messages), the INVLIST 
macro, (12} , must be issued for each line 
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in the system. However, one INVLIST macro 
suffices for all output-only lines to 
stations that do not use invitation 
sequences. ^-Jwo INVLIST entries — 
LIST1050, (a) , and LISTTWX, (V) — appear 
in the sample program. ^^^ 

Note : Either a parameter of + in the 
INVLIST macro or an operator control 
command (see the section "Using TCAM 
Service Facilities" in this chapter) must 
initially activate a station for entering 
messages. 

In the entry LIST1050, for example, • Tl 
+ 6215' indicates that the IBM 1050 
terminal identified as Tl is active for 
entering messages. (6215 is the IBM 1050 
transmission code representation of the 
polling characters A0 in hexadecimal 
notation.) Accordingly, the symbol ' T2A+' 
in the LISTTWX entry indicates an initially 
active line. (Note: The terminal name for 
the line , not the station , must be used. ) 
For a TWX station, the '+' character would 
be followed by an ID sequence instead of 
the polling character used in the LIST1050 
example. In the example, no ID sequence is 
given. The (CPUID) = operand in the 
INVLIST macro for the TWX terminal is 
required. 



D esigning the Messag e Handler 



The major section in a message control 
program is the group of message handlers 
<MH), made up of sets of routines that 
examine and process control information in 
message headers (see Table 31) and perform 
the functions necessary in preparing 
message segments for forwarding to their 
destinations. There is usually a message 
handler for each line group or active 
application program. Each message handler 
usually contains both an incoming and an 
outgoing group. 

A. message may consist of two parts -- 
the header, or control, portion and the 
text portion — depending on the 
application. The sample message control 
program shown in Figure 114 contains four 
message handlers, as listed below. Three 
of these message handlers are based on a 
message header containing the information 
described in the comments that immediately 
precede the first sample message handler, 
o3J . The fourth message handler in the 
sample MCP, MHAPPAPP, handles messages with 
no headers. 



A. message handler (MH1050) for input 
from and output to the IBM 1050 Data 
Communications System Terminal. 



A message handler (MHTWX) for input 
from and output to the Teletypewriter 
Exchange (TWX). 



• A message handler (MHTRMAPP) for input 
from and output to an application 
program running with terminals. 

• A message handler (MHAPPAPP) for input 
from and output to an application 
program that simulates terminal input 
data. This type of message handler can 
be used for testing without terminals 
or for handling messages sent from one 
application program to another, as in 
the sample COBOL programs TLSTTPl (see 
Figure 116) and TESTTP2 (see Figure 
117). 

Two kinds of macro instructions thac may 
t>e included in a message handler are 
functional macros and delimiter macros. 
FuQ9.tiona^_macros perform the specific 
operations necessary for messages directed 
to the message handler. Delimiter macros 
classify and identify sequences of 
functional macro instructions and then 
direct control to the appropriate sequence. 
Table 31 shows some of the functional 
macros that can be used with the delimiter 
macros in the incoming group and the 
outgoing group of the message handler. All 
of these macros are included in the sample 
message handler in Figure 114. 

To decide which macro to place in which 
group, the user must understand which group 
is executed when. This is discussed in the 
description associated with Figure 113. 
The steps executed by a message handler are 
shown at the right-hand side of this 
figure. When messages are received from 
stations, the incoming group of a message 
handler for the line is executed before the 
outgoing group. However, when messages are 
sent to application programs, the outgoing 
group of the message handler for the 
application program is executed first. The 
decision boxes shown in Figure 113 are 
determined by the destination specified in 
the required FORWARD macro of a message 
handler (that is, if the destination is the 
name of a TPROCESS entry, processing is 
required in a an application program; if, 
however, the destination is the name of a 
TERMINAL macro, no more processing is 
required) . 
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Table 31. Macros that can be coded in a 
Message Handler 





| Delimiter | Functional 


Groups | Subgroups 
j. 


| Macros 
-X 


| Macros 

__L 


T 


T 

| STARTMH* 


T 

|CODE 
|LOG 


| Inheader 




| SETSCAN 


Incoming | Subgroup 


| INHDR* 


| MSGTYPE 


Group | 




| ORIGIN 

I darua Dn 
j a v-*c\.r* ethyls 

| TERRSET 


jlnbuf f er 




| CUTOFF 


| Subgroup 


| INBUF 


| MSGEDIT 


j Inmessage 


| INMSG 


| CANCELMG 


| Subgroup 
j. 


| INEND* 
-4. 


| ERRORMSG 


T 


T 


T 

| MSGFORM 
j MSGTYPE 
| MSGEDIT 


|Outheader 




| SETSCAN 


| Subgroup 


| OUTHDR 


| DATETIME 
j SEQUENCE 


Outgoing | 




|LOG 


Group j 




j SETEOF 

T ~ ■ 

| MSGEDIT 


joutbuffer 


1 0UT3UF 


| Subgroup 




|CODE 


j Outmessage 


j OUTMSG 


|HOLD 


| Subgroup 


1 OUTEND* 


| ERRORMSG 



r X J. = =J™„___ ) 

♦The STARTMH macro is always required. 
If the message handler is to handle 
incoming messages, the INHDR, INEND, and| 
OUTEND macros are also required. If the 
message handler is to handle outgoing 
messages, the OUTEND macro is required. 

L J 



Note : For descriptions of other macros 
that can be coded in an MCP, see the 
publication IBM O S Telecommunicat ions 
Access Method (TCAM) Programmer's Guide an d 
Reference Manual . 

A discussion of sample message handlers 
for terminal line groups appears below. 
For discussions of the MHTRMAPP and 
MHAPPAPP message handlers, see the sections 
"A Message Handler for an Application 
Program Running with Terminals" and "A 
Message Handler for an Application Program 
that Simulates Input Data. " 

A MESS AGE HAN DLER FOR THE TERMINA L LINE 
GROUPS : Because the message handlers for 
the 1050 line and the TWX line are similar 
(except for the difference in line control 



characters and the use of the 1050 for 
error messages), the description of the 
message handler for the 1050 (MH1050) given 
below should also suffice for the TWX line 
group (MHTWX). 

The_Incoming Group: The first macro in the 
MH1050 message handler is STARTMH, (13) , 
in which the LC=OUT operand specif ieVthat 
line control characters are to be removed. 
The first macro inthe INHDR, lu) , 
subgroup (CODE) , (15) , translates the 
incoming ^messages to EBCDIC. Then the LOG 
macro, (16) , records the header on the loa 
data set. Even though the CODE macro is 
part of the INHDR subgroup, all buffers of 
the message are translated from line code 
to EBCDIC — not just the first (header) 
buffer. In the normal case, unless the 
line code is EBCDIC, the CODE macro should 
be placed first, as in this example. A 
CODE macro must be issued before an ORIGIN 
macro, since the name in the header is 
checked against the terminal names, which 
are in EBCDIC. The name in the header, 
therefore, cannot be located unless it has 
first been translated. The same 
translation requirements apply to such 
macros as SETSCAN, (17) , in the example. 
In this case, if theV'$' in the message 
were not first translated to EBCDIC, the 
C'$' would have to be specified in line 
code. - - 

The SETSCAN macro, (l7) , sets the scan 
pointer to "$" inline header, and the 
MSGTYPE macros, nj) , that follow cneck 
the character in th& next field (with 
fields separated by at least one blank 
character) for one of the four codes that 
represent possible message destinations. 
If the scan yields a match between a field 
in the incoming message and the code for 
one of the MSGTYPE macros, the macros 
between this MSGTYPE macro and the next 
MSGTYPE macro are executed. Control is 
then given to the next subgroup (INBUF), 
(22) . When a MSGTYPE match is found, the 
ORIGIN macro, 4^)-n » i s issued. The 
FORWARD macro, ^V) , which is always 
required, transmits the message to the 
destination specified. 

If there is no match with any of the 
operands specified in the MSGTYPE macros, 
the last MSGTYPE macro, which has a blank 
operand field, is executed. The required 
FORWARD macro follows, and the TERRSET 
macro, (21) , sets the user error bits in 
the error record for the message. 



In the_iNBUF subgroup, \£2) , the CUTOFF 
macro, (23) , limits the size of the 
incoming messages and checks for station 
malfunction. The insertion of the_RECDEL 
character by the MSGEDIT macro, G4) , 
allows for record delimiters in the 
message, needed when the COBOL program 
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reads in segment mode. The INMSG subgroup, 
(25) , checks the error bits in the error 
record for this message and either cancels 
the message via the CANCELMG macro, (26) , 
and/or sends an error message to the Y"050 
terminal using theERRORMSG macro, (27) . 
The INEND macro, (28) . a required 
delimiter macro, signifies the end of the 
incoming groups. 

The_ Out going Group: The macros discussed 
below, known as the outgoing group, are 
executed when messages are transmitted to 
the 1050 terminal. In the QDTHDR subgroup, 
(29) , the MSGFORM macro, GO) , causes 
lxne control characters to be inserted in 
the outgoing message. (Unless the user 
provides line control characters himself, 
this macro must be coded. > The MSGTYPE 
macro determines the type of message, so 
that a message can be processed either as 
an ordinary message or as an error message. 

For every error message, the SETSCAN 
macro returns the scan pointer to the 
beginning of the message, and the MSGEDIT 
macro inserts the "NL" character before the 
message text. Processing of errors messages 
resumes in the OUTBUF subgroup, (33) , of 
the message handler. 

For the non-error messages, the MSGEDIT 
macro also inserts "NL" at the beginning of 
the message. Then the SETSCAN macro sets 
the scan pointer to the period at the end 
of the message header so that pertinent 
information can beinserted there. The 
DATETIME macro, By , records in the 
message being sent the date and time this 
maqro is executed. The SEQUENCE macro, 
62) , inserts a sequence number, and the 
LOG macro records the control information 
contained in the message header. 



In the OUTBUF subgroup, (33) , of this 
message handler, the MSGEDIT macro inserts 
an "NL" character for every record 
delimiter character in the message. 
Because in the incoming group the RECDEL 
character is inserted for every "NL" and 
"LF" character, for a message that is 
simply transmitted from one terminal to 
another the message handler appears to send 
the same line control characters it 
receives. For a message sent by a COBOL 
program, on the other hand, wether or not 
record delimiter characters remain depends 
on the mode specified in the RECEIVE or 
SEND statement. (Tnat is, when the 
programmer receives a message in segment 
mode, the record delimiter character is 
removed; when the programmer receives a 
message in message mode, the record 
delimiter is not removed. Accordingly, 
when the programmer sends a message in 
segm ent mode, the record delimiter 
character is added; when the programmer 
sends a message in message mode, the record 



delimiter is not added. ) The next MSGEDIT 
macro inserts 13 idle characters after 
every "NL" character placed in the message, 
to allow the terminal sufficient time to 
return its carriage before receiving the 
next line. Finally, the CODE macro 
translates from EBCDIC to line code when no 
more handling is required with macros that 
operate in EBCDIC. 

Like the INMSG subgroup (see "The 
Incoming Group"), the OUTMSG subgroup, 
(34) , checks the error bit in the error 
record for the message and transmits error 
messages, if any, .-to the 1050 terminal. 
The HOLD macro, G5) , is invoked only if 
there are hardware errors. Accordingly, a 
terminal placed in HOLD status is not 
released until an operator control message 
is issued. The OUTEND macro, Gb) , 
signifies the end of the outgoing group. 

A MESSAGE HANDLER FOR AN APPLICATION 
PROGRAM_RUNNING_WITH_TERMINALS : The 
MHTRMAPP message handler handles messages 
transmitted by a terminal for the 
application program that is sending and 
receiving messages from terminals. Like 
the message handler discussed earlier, 
MHTRMAPP includes both an incoming group 
and an outgoing group. 

In this message handler, because 
messages are sent to the application 
program from a terminal, the outgoing group 
headed by the OUTHDR macro, (37) , is 
executed first. The first macro (MS3EDII) 
deletes any characters (for example, "NL", 
"CR", or "LF") that have preceded "$" in 
the header. This step is necessary because 
of the application program's expectation of 
receiving a fixed-length header beginning 
with "$". The next macro (SETSCAN) sets 
the scan pointer over the "$" and the 
MSGTYPE field. Then the SEQUENCE macro 
numbers the messages sent to the 
application program, and the LOG macro 
records the information contained in the 
message header. 

The next SETSCAN macro sets the scan 
pointer over the source field in the header 
so that it points instead to the EOF field. 
The SETEOF macro identifies the last 
message in a data file being processed by 
an application program. If the character 
specified at the location pointed to by the 
scan pointer (and given as an operand in 
the SETEOF macro) is "F", the first RECEIVE 
statement issued by the COBOL program after 
receipt of the message causes the MCP to 
enter an application program EODAD routine. 
As far as the COBOL user is concerned, this 
section sets the "ETI" indicator in the 
field referred to by the END KEY clause in 
the input communication description (CD). 
The OUTMSG subgroup is not included in this 
message handler because it is not executed 
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for messages sent to an application 
program. Nevertheless, the OUTEND 
delimiter macro signifies the end of the 
outgoing group. 



The macros in the incoming group of this 
message handler, headed by the INHDR macro, 
(38) , are executed when messages are 
received from the COBOL program. The LOG 
macro records the information contained in 
the header, and the FORWARD macro, wnich is 
always required, specifies "DEST=PUT" as 
the message destination. This will cause 
the message to be forwarded to the 
destination the COBOL program has indicated 
in the output CD. The INMSG subgroup that 
follows checks to see whether sufficient 
buffer units are available for the message 
and verifies that the destination specified 
is valid. The INEND delimiter macro then 
specifies the end of the incoming group. 



ASSEMBLING, LINK-EDITING, AND EXECUTING AN 
MCP 



The assembly, link-edit, and execution 
steps of a TCAM MCP are similar to these 
steps for any other problem program running 
under OS. The job control statements given 
below for these three steps are guidelines 
only. 



Assembling__an_MCP 



A typical control card sequence for 
assembling a TCAM MCP is as follows: 

//ASSEMBLY JOB MSGLEVEL=1 
//STEP1 EXEC ASMFC 
//ASM. SYSIN DD * 



A MESSA GE HAN DLER FOR AN APPL ICATION 
PROG RAM THAT SIMULATES TERMINA L INPUT DATA : 
The MHAPPAPP message handler is for 
messages having no header. As a result, 
the only macro in the outgoing group is the 
delimiter macro OUTEND, (39) , which is 
always required. 



The incoming group contains both the 
INHDR, wo) , subgroup, containing the 
required FORWARD macro, and the INMSG 
subgroup, which checks for availability of 
sufficient buffer units and verifies that 
the destination specified is valid. The 
required INEND delimiter macro is present. 



{MCP Source Deck} 



Link-Editing an MCP 



PUTTING THE MCP TOGETHER 



The- following -is -a- typical control ca rd- 
sequence for link-editing an MCP: 



MSGLEVEL=1 

PGM=ILWL, PARM=' XREF, LIST, 

LET' , REGI0N=9bK 

SYSOUT=A 

UNIT=SYSDA, 

SPACE=ll024, (200, 20) ) 

DSNAME=SYS1. TCAMLIB, 

DISP=OLD 

DSNAME=SY3l. TELCMLIB, X 

DI3P=0LD 

DSNAME=SYSl.MACLIB, X 

DISP=OLD 



//LINKEDIT 


JOB 


//STEP1 


EXEC 


// 




//SYSPRINT 


DD 


//SYSUT1 


DD 


// 




//SYSLMOD 


DD 


//SYSLIB 


DD 


// 


DD 


// 




//SYSLIN 


DD 



This section names the parts of the MCP 
described earlier, explaining how to 
arrange them in relation to one another and 
how to assemble, link-edit, and execute a 
TCAM MCP. The five sections of an MCP 
include those previously discussed — an 
activation and deactivation section- a data 
set definition section, a terminal and line 
control area section, a message handler 
section — and an optional user routine 
section (that is, user subroutines called 
by a message handler, as well as exit 
routines referred to by the INTRO macro, by 
DCB macros, and by the STARTMH macro) . The 
only stipulation about ordering these 
sections is that the activation and 
deactivation section must come first. 



{MCP Object Module} 

NAME TCAMPROG(R) 

Note : In this example, the MCP load module 
is to be placed in a user-created private 
library called SYS1 S TCAMLIB; 



Exe cu ting an M CP 



The TCAM MCP is normally executed as the 
highest-priority task in the 
highest-priority partition or region in the 
system. It may have an equal priority, but 
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//EXECMCP 


JOB 


// 




//GOSTEP 


EXEC 


//STEPLIB 


DD 


// 




//DD1050 


DD 


// 


DD 


// 


DD 


//DD27U0 


DD 


// 


DD 


// 


DD 


//QFILE 


DD 


//LOGFILE 


DD 


//SYSABEND 


DD 


Notes: 





it should never be assigned a lower 
priority. A. typical control card sequence 
for executing an MCP is the following: 



' EXECUTE MCP • , MSGLEVEL=1 , 

PRTY=12 

PGM=TCAMPROG, REGION=100K 

DSNAME=SYSl. TCAMLIB, 

DISP=SHR 

UNIT=025 

UNIT=026 

UNIT=027 

UNIT=015 

UNIT=016 

UNIT=017 

DSNAME=MSGQ, DISP=OLD 

DSNAME=LOGF, DISP=OLD 

SYSOUT=A 



1. In this example, the MCP has two line 
group data sets, each containing three 
lines; no checkpoint facility is 
included. (For a discussion of the DD 
cards for a checkpoint data set, see 
the section "Defining the Checkpoint 
Data Set. " > 



2. The QFILE DD statement is for a 
message queues data set residing on 
disk; QFILE is the name specified in 
the DDNAME= operand of the DCB macro 
for this data set, and MSGQ is the 
name of the data set specified by the 
DSNAME operand of the IEDQDATA DD 
statement for the IEDQXA utility used 
to preformat disk message queues data 
sets residing on disk (see the section 
"Defining the Message Queues Data 
Sets"). 

3. If the data set is not cataloged, the 
UNIT= and VOLUME= operands must be 
included in the DD statement for the 
disk message queues data set. 

4. The //LOGFILE DD card must be included 
if the LOG data set is to be used. 



After a checkpoint data set is set up 
and the MCP has terminated normally, toe 
programmer should replace the DD card 
described above with one of the following 
type: 

//CFILE DD DSNAME=CPDS, DISP=OLD, 

VOL=SER=DBl97, UNH'=2314 

Def i ning_Line _Gr oup_Da ta _S e t s : The user 
must include in his job control statements 
at least one DD statement for each line 
group data set, but he has two options for 
handling these definitions. 



1. 



2. 



3. 



//LN1 
//LN2 



If a UNITNAME macro is issued for a 
line group at system generation time, 
then a single DD statement may be 
issued for this line group at MCP 
execution time. For example, a 
UNITNAME macro could be issued to 
define a group of lines as follows: 

UNITNAME UNIT=(040, 041) 
NAME=GROUPLINE 

Where the two numerals in the 
UNIT-operand parameter represent the 
hardware addresses of two lines in a 
line group. At execution time for the 
MCP, the following DD statement might 
be issued for this line group: 

//LNS DD UNIT=(GROUPLINE, 2) 

Where the line group data set would be 
made up of two lines defined by the 
UNITNAME macro. 

A DD statement may be issued for each 
line in a line group, as in the DD 
cards for line group DD1050 and line 
group DD2740 in the sample JCL 
statements given in section "Executing 
an MCP. " 

The following DD cards were used to 
execute the sample message control 
program shown in Figure 112. 

DD UNIT=040 (for the 1050 terminal) 
DD UNIT=041 (for the TWX terminal) 



Defi ning the Chec k point Data Set : One DD 
statement that may or may not catalog the 
data set must be issued for the checkpoint 
data set. However, if it is not cataloged, 
the user should allocate the data set by 
specifying DISP= (NEW, KEEP) as in the 
example and subsequent uses of the data set 
must contain the UNIT= and VOL=SER=keyword 
operands, given below. 

//CFILE DD DSNAME=CPDS,UNIT=2314, X 

// VOL=SER, DB197, X 

// SPACE=(TRK, (5)), X 

// DISP=( NEW, KEEP) 



Def in in g the Message Queues Data Sets : The 
number of message queues data sets require! 
for an MCP depends on the types of queues, 
which depend on the application. ICAM 
supports three types of data sets -- a main 
storage data set, a reusable disk set, and 
a nonreusable disk data set. iFor 
checklists governing specification of the 
three types of message queues data sets, 
see the publication IBM OS 
Telecommuni cations Access Method (TCAiyn 
Progr ammer' s Gui de a nd Re ference Manual. ) 

TCAM expects the disk message queues 
(both reusable and nonreusable) to be 
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totally preformatted. The COBOL user 
should engage the IEDQXA utility routine to 
perform this task prior to initially of a 
set of job control statement used to invoke 
this routine. 

N ote : The value given in the KEYLEN 
parameter must be the same as that 
specified in the KEYLEN operand of the 
INTRO macro (see the section "Defining the 
Buffers"). 



application of processing data. This 
program accepts messages transmitted from a 
remote station, formats the message, and 
then transmits each complete message to the 
destination specified. Ihe COBOL program 
TESTTP1 (shown in Figure 118) simulates 
terminal input data. The user can, 
therefore, test an installation-written 
COBOL TP program by running it with the 
sample MCP and TESTTP1. 



//JOBNAME JOB user information 

//FQRMATQ EXEC PGM= IEDQXA 

//SYSPRINT DD SYSOUT=A 

//IEDQDATA DD DSN=MSGQ, DISP=( , CATLG) , X 

// SPACE=(CYL, (5,5), ,CONTIG) X 

// UNIT=(2311, 1) , X 

// VOL=SER=333333, X 

// DCB=(,KEYLEN=100) 

/* 



WRITING A TC AM- COMPATIBLE COBOL PROGRAM 



Two of the chief processing applications 
for which COBOL programs can be written are 
inguiry processing and processing collected 
data. An inguiry-processing COBOL program 
receives messages from stations, processes 
the data-,- and then sends replies to the 
originating stations. Depending on the 
inguiry, the COBOL program may transmit 
either the information reguested or a 
message stating that this information is 
unavailable and telling when it can be 
provided. The COBOL program that simply 
processes data collected by a message 
control program can either operate 
concurrently with the collection of data by 
the MCP or be loaded and initiated at a 
later time. 

The sample COBOL TP program TFSTTP2 
(shown in Figure 119) represents an 



TESTING A COBOL TP PROGRAM 



Depending on the status of an 
installation' s teleprocessing system, tne 
user can code any one of three sets of JCL 
to run a teleprocessing job. A system that 
is fully operational has a message control 
program with a user-designated message 
handler for each type of teleprocessing 
situation expected, as well as remote 
terminal hook-ups. The user whose system 
is only partially developed or is still in 
the design stage may, nevertheless, wish to 
test COBOL teleprocessing programs using 
BSAM. 

Accordingly, the JCL shown in Figure lis 
is for a strictly BSAM situation (that is, 
for a teleprocessing program that is to be 
run without either an MCP or hardware) ; the 
JCL shown in Figure lib is for a 
guasi-terminal situation (that is, with MCP 
but without hardware) ; and the JCL shown in 
Figure 117 is for a teleprocessing job 
running with a remote terminal. For both 
the non-terminal and the guasi-terminal 
situation an input data set must be 
created. To run a COBOL teleprocessing 
program with a terminal hook-up, only the 
teleprocessing program itself is needed. 
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r 

//TESTTP1 JOB user information 
// EXEC UCOBFCLG 

//COB.SYSIN DD * 

{Source deck for TESTTP1 program (Figure 118)} 
/* 

//GO.TSTTP DD 1 UNIT=2400, LABEL=( , NL) , VOLf SER=NI195, DCB= (LRECL=50, BLKSIZE=50, X 

// RECFM=F,DEN=2) 

//GO. COBTPOUT DD 2 UNIT=2314, VOL=SER=231400, DSN=£1, DISP= (NEW, PASS) , SPACE= (CYL, (1, 2)) 

//TESTTP2 JOB user information 

// EXEC UCOBFCLG 

//COB. SYSIN DD * 

{Source deck for TESTTP2 program (Figure 119)} 
/* 

//GO.Q1 DD 3 DSN=P1, VOL=SER=231400,UNIT=2314,DISP= (OLD, PASS) 
//SO. COBTPOUT DD* DSN=P2, VOL=SER=231400, UNIT=2314, DISP= (NEW, PASS) , SPACE= (CYL, (1,2)) 

user information 

PGM=IMASP=AP 

DSNAME=data set to be printed, UNIT-2314, VOL=SER=231400, X 

DISP=OLD, DCB=DSORG=PS 

SYSOUT=A 

* 

ABSDUMP ALL 
/* 



//DUMPIT 


JOB 


// 


EXEC 5 


//SYSLIB 


DD 


// 




//SYSPRINT 


DD 


//SYSIN 


DD 



Not es : 

1. Input sequential file with records of 50 characters each (BSAM JCL) . 

2. Output data set that simulates sending messages to a terminal named * PI' . 

3. Input data set that simulates reading messages from a terminal named 'PI 1 . 

4. Output data set that simulates sending messages to a terminal named * P2' . 

5. This job prints out the records in the simulated data set. For further 
information, see the publication IBM_OS_Service_Aids, Order No. GC28-6719. 

L 

Figure 115. Sample JCL for Running a Teleprocessing Job without Hardware. 
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r 

//TESTTP1 JOB user information 
// EXEC UCOBFCLG 

//COB.SYSIN DD * 

{Source deck for TESTTPl program (Figure 118) > 
/* 

//GO.TSTTP DD 1 UNIT=2400, LABEL=( , NL) , VOL=SER=NI195, DCB= (LRECL=50, BLKSIZE=50, 

// RECFM=F, DEN=2) 

//GO. COBTPOUT DD 2 QNAME=POUTl 

//TESTTP2 JOB user information 

// EXEC UCOBFCLG 

//COB.SYSIN DD * 

{Source deck for TESTTP2 program (Figure 119)} 
/* 

//GO. Ql DD 3 QNAME=P1 
//GO. COBTPOUT DD* QNAME=POUTl 
//DUMPIT JOB user information 
// EXEC IEDQXC 

//DISQ01 DD 5 DSN=MSGQ,VOL=SER=DBl97,UNIT=2314 l DISP=SHR 
//SYSPRINT DD SYSOUT=A 
/* 
y ^ 

Notes : 



1. Input sequential file with records of 50 characters each. (This is the same JCL as 
in BSAM. ) 

2. Output is sent to an MCP message queue named ' PI* , which is defined for processing 
by a COBOL program. 

3. Input- is received from the- MCP message queue named 'PI'-, 

4. Output is sent to an MCP message queue named ' P2', which is defined for processing 
by a COBOL program. 

5. This job prints out records in the MSGQ queue. For further information, see the 
publication IB M OS Teleco mmunications Recess Method (TCAM) Programmer's Guide and 

! R efer ence Material. Order No. GC 30-2024. 

i j 

Figure 116. Sample JCL for Running a Teleprocessing Job in a Quasi-Terminal Environment. 



r 

| //TESTTP2 JOB user information 

|// EXEC UCOBFCLG 

| //COB.SYSIN DD * 

I {Source deck for TESTTP2 program (Figure 119)} 

|/* 

| //GO. Ql DD 1 QNAMS=P1 

I //GO. COBTPOUT DD 2 QNAME=POUTl 

j. 

1 Not es : 

i 

|1. The input is received from the MCP message queue 'Pi'. 



| 2. The output is sent to an MCP message queue defined for a terminal. 

L 

Figure 117. Sample JCL for Running a Teleprocessing Job with a Remote Terminal. 
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COMMUNICATING BETWEEN A COBOL PROGRAM &ND 

THE MCP 



The TCAM message control program routes 
messages between a COBOL teleprocessing 
program and remote stations. Because the 
MCP performs the input/output operations 
necessary for the COBOL teleprocessing 
program, the user must establish an 
interface between these two programs by 
doing the following: 

• Defining the interface 

• Activating the interface 

• Transferring messages between the COBOL 
program and the MCP 

• Deactivating the interface 

In each of the sections that follow, both 
COBOL statements and TCAM macros, as well 
as their relationship, are described as 
appropriate. The encircled numerals in 
this discussion refer to the sections 
similarly labeled in the sample COBOL 
teleprocessing program TESTTP2 shown in 
Figure 119. 



Defi n ing the Interface 



The Communication Section in the COBOL 
program and the PCB and TPROCESS macros in 
the message control program set up the 
interface between the two programs. 

D efi n ing Input and Output D at a Se ts : At 
execution time, one DD statement must be 
provided for each SYMBOLIC QUEUE name 
specified in an input CD. A prototype of 
such a statement is 



//ddname 



DD QNAME=procname 



where " procname" is the name of the process 
entry in the terminal table to which this 
entry refers (see the section "Defining 
Terminal and Line Control Areas"). 

As in the following example from the 
sample program TESTTP2 (shown in Figure 
92.7), the COBOL user should specify the 
SYMBOLIC QUEUE names for the ddnames and 
the corresponding TPROCESS entry names for 
the procname. In TESTTP2, one input queue 
and one output queue are defined. The DD 
card for the input queue is: 

//Ql DD QNAME=P1 



Similarly, the COBOL programmer must 
provide a DD card for the process entry 
defined in the MCP to send messages from 
the COBOL program. As in the example that 
follows, the ddname must be C0BTP0U1, and 
the QNAME must be the name of a TPROCESS 
entry for an output process entry* The MCP 
should have a queue defined as P2, but no 
DD statement is needed for this queue. 



//COBTPOUT DD QNAME=POUTl 



The user should notice that these 
destination queues are among those 
specified in the message control program 
via the TPROCESS macro. For examples of 
these TPROCESS entries, see the discussion 
the "TPROCESS Macro" under "Defining 
Terminal and Line Control Areas". 



In a COBOL TP program, the user can 
specify one through three levels of 
subqueues from which data can be received. 
This feature allows the COBOL object 
program, at execution time, to make use of 
pre-defined queue structures, and to access 
all or parts of such structures. If 
pre-defined queue structure are used, each 
lowest level subqueue name in the structure 
corresponds to a TCAM queue and must, 
therefore, have an associated DD card 
pointing to a TPROCESS entry in the MCP 
terminal table. Each subqueue must be 
defined in the communication description 
(CD) of the COBOL source program and have 
been defined earlier in a queue structure 
description (see the sections "Queue 
Structure Considerations" and 
"Communication Section" in the chapter on 
"Programming Techniques"). 



If the user wishes to access the next 
message in the queue structure, regardless 
of which sub-queue that message may be in, 
he specifies the queue name only and 
initializes the sub-queue names to SPACES. 
The MCP, when supplying the message, 
returns to the COBOL object program any 
applicable sub-queue names via the data 
items in the associated input CD. If, 
however, the programmer desires the next 
message in a given sub-queue, he must 
specify both the queue name and any 
applicable sub-queue names. Once a program 
has begun receiving any part of a message 
from a queue (or sub-queue), subsequent 
requests must specify all applicable names 
until end of message (EMI) is indicated. 
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001010 IDENTIFICATION DIVISION. 

001020 PROGRAM-ID. 

001030 TESTTP1. 

001080 DATE-COMPILED. DEC 9,1971 

001100 REMARKS. THE SAMPLE COBOL TELEPROCESSING PROGRAM THAT 

FOLLOWS SERVES AS A SIMPLE ILLUSTRATION OF THE COBOL TELE- 
PROCESSING FEATURE. THIS PROGRAM READS IN A FILE OF 50- 
CHARACTER MESSAGES, TRANSMITTING THEM ONE BY ONE TO THE 
SPECIFIED DESTINATION. 

001160 

001170 ENVIRONMENT DIVISION. 

001180 INPUT-OUTPUT SECTION. 

001190 FILE- CONTROL. 

001200 SELECT MASTER-FILE 

001210 ASSIGN TO UT-2400-S-TSTTP. 

002010 DATA DIVISION. 

002020 FILE SECTION. 

002030 FD MASTER-FILE 

0020 40 RECORDING MODE IS F 

002050 LABEL RECORDS ARE STANDARD 

002060 DATA RECORD IS RECORDl. 

002070 01 RECORDl PIC X(50). 

003010 WORKING- STORAGE SECTION. 

003110 

003120 01 IDENT-SEND. 

003130 02 I-SEND PIC X(50). 

* SET UP A WORK AREA OF 50 CHARACTERS 
003150 

* THE COMMUNICATION SECTION MUST BE SPECIFIED IN A COBOL PROGRAM 

* THAT IS TO UTILIZE THE COBOL TELEPROCESSING FEATURE. THE 

* COMMUNICATION DESCRIPTION (CD) ENTRIES THAT APPEAR IN THIS 

* GROUP OF SOURCE STATEMENTS ESTABLISH THE INTERFACE BETWEEN THE 

* COBOL" OBJECT PROGRAM AND THE MESSAGE CONTROL PROGRAM (MCF) . 
004010 COMMUNICATION SECTION. 

004120 CD CDNAME-OUT FOR OUTPUT 
004130 TEXT LENGTH IS TEXTLNTH-OUT 

* SPECIFY LENGTH OF OUTPUT MESSAGE. 
004140 STATUS KEY IS STATKY-OUT 

* PROVIDE INFORMATION ON MESSAGE STATUS. 
004150 ERROR KEY IS ERRKY 

* PROVIDE ERROR INFORMATION. 
004160 SYMBOLIC DESTINATION IS SYMDES. 

* SPECIFY OUTPUT QUEUE. 
004170 

005010 PROCEDURE DIVISION. 

005020 START-JOB. 

005030 DISPLAY 'BEGIN TESTTP1'. 

* START THE COBOL TELEPROCESSING PROGRAM. 
005040 OPEN INPUT MASTER-FILE. 

* OPEN THE INPUT FILE. 
005045 READ-ROUTINE. 

005050 READ MASTER-FILE INTO IDENT-SEND 
005060 AT END GO TO END-ROUTINE. 

* PLACE INPUT RECORDS IN A WORK AREA UNTIL END OF FILE IS 

* REACHED. 
006010 SEND-ROUTINE1. 

006020 MOVE 'PI' TO SYMDES. 

* SET UP OUTPUT DESTINATION. 
006040 MOVE 50 TO TEXTLNTH-OUT. 

* IDENTIFY MESSAGE LENGTH AS 50. 

006060 SEND CDNAME-OUT FROM IDENT-SEND WITH EMI. 

* TRANSMIT A COMPLETE MESSAGE. 

006070 PERFORM CHECK-SEND THRU CHECK-EXIT. 
006080 GO TO READ- ROUTINE. 

Figure 118. Creating a TCAM Data Set for Testing without Terminals 
(Part 1 of 2) 



Using the Teleprocessing feature 371 



* EXECUTE USER-WRITTEN CODE FOR CHECKING ON THE SUCCESSFUL 

* COMPLETION OF MESSAGE TRANSMISSION. IF END OF FILE IS 

* REACHED, GO TO END-OF-JOB ROUTINE. OTHERWISE, GET THE NEXT 

* RECORD. 
008010 CHECK-SEND. 
008020* 

008021* 
008022* 

008030* USER CHECKING ROUTINE FOR DETERMINING THE 

008040* SUCCESSFUL COMPLETION OF THE SEND. 
008050* 
008160 

008170 CHECK-EXIT. 

008180 EXIT. 
**008180* 
008190 

011110 END-ROUTINE. 

011111 CLOSE MASTER-FILE. 

* CLOSE THE INPUT FILE. 

011150 DISPLAY 'SUCCESSFUL END OF TES1TP1' . 

* TERMINATE THE PROGRAM. 
011160 STOP RUN. 

Figure 118. Creating a TCAM Data Set for Testing without Terminals (Part 2 of 2) 
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001010 IDENTIFICATION DIVISION. 

001020 PROGRAM-ID. 

001030 TESTTP2. 

001080 DATE-COMPILED. DEC 9,1971 

001100 REMARKS. THE SAMPLE COBOL TELEPROCESSING PROGRAM THAT 

FOLLOWS SERVES AS A SIMPLE ILLUSTRATION OF THE COBOL TELE- 
PROCESSING FEATURE. THIS PROGRAM SETS UP A DESTINATION 
FOR INCOMING MESSAGES, AND THEN READS THEM, ONE BY ONE, 
INTO A WORK AREA. THE PROGRAM BUILDS 50-CHARACTER MESSAGES 
AND SENDS THEM TO THE MCP WITH THE END-OF-MESSAGE (EMI) 
INDICATOR. WHEN ALL THE INCOMING MESSAGES HAVE BEEN PRO- 
CESSED, THE MESSAGE 'SUCCESSFUL END OF TESTTP2* IS PRINTED 
ON THE CONSOLE, AND THE PROGRAM IS TERMINATED. 

001120 

001130 

001170 ENVIRONMENT DIVISION. 

001180 CONFIGURATION SECTION. 

001190 INPUT-OUTPUT SECTION. 

001200 

002010 DATA DIVISION. 

WORKING- STORAGE SECTION. 

003110 

(003120 01 IDENT-SEND. 

)003130 02 I-SEND PIC X(50). 

J003160 01 IDENT-REC. 

(003170 02 I-REC PIC X(50). 

003190 

♦ THE COMMUNICATION SECTION MUST BE SPECIFIED IN A COBOL PROGRAM 

♦ THAT IS TO UTILIZE THE COBOL TELEPROCESSING FEATURE. THE 

♦ COMMUNICATION DESCRIPTION (CD) ENTRIES THAT APPEAR IN THIS 

♦ GROUP OF SOURCE STATEMENTS ESTABLISH THE INTERFACE BETWEEN THE 

♦ COBOL OBJECT PROGRAM AND THE MESSAGE CONTROL PROGRAM (MCP). 
COMMUNICATION SECTION.- - - 

004120 CD CDNAME-OUT FOR OUTPUT 
004130 TEXT LENGTH IS TEXTLNTH-OUT 

♦ SPECIFY LENGTH OF OUTPUT MESSAGE. 
00414 STATUS KEY IS STATKY-OUT 

♦ PROVIDE INFORMATION ON OUTPUT MESSAGE STATUS. 
004150 ERROR KEY IS ERRKY 

♦ PROVIDE ERROR INFORMATION. 
004160 SYMBOLIC DESTINATION IS SYMDES. 

♦ SPECIFY OUTPUT QUEUE. 
004170 

♦♦004020 CD CDNAME-IN FOR INPUT 
004030 SYMBOLIC QUEUE IS SYMQ 

♦ IDENTIFY INPUT MESSAGE QUEUE. 
004 04 MESSAGE DATE IS MSGDATE 
004050 MESSAGE TIME IS MSGTIME 

♦ PROVIDE DATE AND TIME OF RECEIPT OF MESSAGE. 
004060 SYMBOLIC SOURCE IS SYMSOURCE 

♦ IDENTIFY THE MESSAGE SOURCE. 
004070 TEXT LENGTH IS TEXTLNTH-IN 

♦ SPECIFY THE EXPECTED LENGTH OF INPUT MESSAGE. 
004080 END KEY IS ENDKY 

♦ PROVIDE CODE FOR ACTIVATING END-OF-JOB ROUTINE. 
** FOR A RECEIVE MESSAGE: 

♦ A CODE OF 3 INDICATES END OF TRANSMISSION (ETI). 

♦ A CODE OF 2 INDICATES END OF MESSAGE ( EMI ) . 

♦ A CODE OF INDICATES RECEIPT OF LESS THAN A MESSAGE. 
♦♦ FOR A RECEIVE SEGMENT: 

♦ A CODE OF 3 INDICATES END OF TRANSMISSION (ETI). 
+ A CODE OF 2 INDICATES END OF MESSAGE (EMI). 

♦ A CODE OF 1 INDICATES END OF SEGMENT (ESI) 

♦ A CODE OF INDICATES RECEIPT OF LESS THAN A SEGMENT. 

Figure 119. A COBOL Program That Processes TCAM Messages 
(Part 1 of 2) 
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*♦ HIERARCHY — 0, ESI, EMI, STI-WHEN MORE THAN ONE CONCURRENTLY- 

* HIGH LEVEL APPEARS. 
004090 STATUS KEY IS STATKY-IN 

* PROVIDE INFORMATION ON INPUT MESSAGE STATUS. 
004100 QUEUE DEPTH IS QDEPTH. 

* SPECIFY DEPTH OF INPUT QUEUE. 
004110 

♦♦002100 
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PROCEDURE DIVISION. 

DISPLAY 'BEGIN TESTTP2' . 
RECV-DATA. 
00904 MOVE ' Ql ' TO SYMQ. 

* SET UP INPUT DESTINATION. 
009050 RECEIVE CDNAME-IN MESSAGE INTO IDENT-REC 
009055 NO DATA GO TO END-ROUTINE. 

* ACCEPT INPUT MESSAGES, ONE BY ONE, AS ON A SEQUENTIAL FILE. 

* WHEN ALL MESSAGES HAVE BEEN PROCESSED, INVOKE END-OF-JOB 

* ROUTINE. 
009060 CHECK-RECEIVE. 
009070+ 

009 080+ USER CHECKING ROUTINE FOR DETERMINING THE 
009090+ SUCCESSFUL COMPLETION OF THE RECEIVE. 
009100* 

009110 PROCESS-DATA. 
009120* 

009130* USER ROUTINE TO BUILD MESSAGE TO BE SENT. 
009140* 
**006010 SEND-ROUTINE1. 

006020 MOVE ' P2' TO SYMDES. 

* SET UP OUTPUT DESTINATION. 

* NOTE: FOR THE NON-TERMINAL AND PARTIAL TERMINAL SITUATIONS, 

* 'P2' SHOULD BE SPECIFIED AS THE SYMBOLIC DESTINATION. FOR 

* A COBOL PROGRAM RUNNING WITH TERMINALS, ' Tl' SHOULD BE 

* SPECIFIED. 

00604 MOVE 50 TO TEXTLNTH-OUT. 

* SPECIFY LENGTH OF OUTPUT MESSAGES. 
006060 SEND CDNAME-OUT FROM IDENT-SEND WITH EMI. 

* TRANSMIT FORMATTED MESSAGE, WITH THE CODE FOR A COMPLETE 

* MESSAGE. 
006070 PERFORM CHECK-SEND THRU CHECK-EXIT. 

* INVOKE USER-WRITTEN ROUTINE FOR CHECKING MESSAGE TRANSMISSION. 

* ACCEPT THE NEXT MESSAGE FROM THE INPUT QUEUE. 
006090 GO TO RECV-DATA. 
007120 

008010 CHECK-SEND. 
008020* 

008030* USER CHECKING ROUTINE FOR DETERMINING THE 
008040* SUCCESSFUL COMPLETION OF THE SEND. 
008050* 

008170 CHECK-EXIT. 
008180 EXIT. 
008190 

011110 END-ROUTINE. 

011150 DISPLAY 'SUCCESSFUL END OF TESTTP2*. 
011160 STOP RUN. 



Figure 119. A COBOL Program That Processes TCAM Messages (Part 2 of 2) 
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Defining Process Contr ol 3lock s: In the Note; 

MCP the user must also code a process 

control block (PCB) for each active 

application program running with the MCP. 

The PCB macro specifies the name of the PCB 

process control block generated by the 

macro. The process control block is 

referred to in the TPROCESS macro (see 

"Defining the MCP Data Sets and Process 

Control Blocks"). 



Activ ating the In te rface 



The COBOL programmer coding a program 
for a teleprocessing application 
initializes work areas, MM , and activates 
the COBOL program as for any other OS 
application. In this application, the job 
begins with the use of the DISPLAY 
statement "BEGIN TESTTP2, " (T). The COBOL 
programmer need not be concerned with how 
the interface is activated. The interface 
is activated when the first RECEIVE or SEND 
statement is issued. 



T ran sferring Messag es be t wee n the COBOL 
P rog ram an d th e MC P 



TCAM enables the application programmer 
to obtain messages from the MCP and to 
return response messages to the MCP. 
Specifically, the COBOL programmer can use 
either the RECEIVE statement or the SEND 
statement to transfer data between the MCP 
and the COBOL program, depending on the 
direction of the flow of data. 

Ihe_ RECEI VE State ment: This COBOL source 
statement causes transmission of message 
data from an input queue to a 
user-specified work area in the COBOL 
program. In the sample COBOL 
teleprocessing program shown in Figure 119, 
the RECEIVE statement, (?) , transfers data 
from the input queue rer*e"rred to by SYMQ to 
a work area. The COBOL sentence before the 
RECEIVE statement is "MOVE 'Ql* TO SYMQ," 
so the data is received from Ql. 



For an additional example of trie format 
of the RECEIVE statement and the SEND 
statement, see the section "Procedure 
Division" in the chapter on 
"Programming Techniques". 

The amount of data transferred from the 
MCP to a COBOL program by a single 
RECEIVE statement, or transferred from 
an application program to the MCP by a 
single SEND statement, is called a 
"work unit". Each work unit is 
processed in a user-designated work 
area in the COBOL program. 



Deactivating t he Inte rface 



As in all American National Standard 
COBOL programs, the teleprocessing 
application user returns control to the 
system by issuing a STOP RUN statement, 

©• 

Note: So that the COBOL program can give 
control to the STOP RUN statement, the MCP 
writer should include in the message header 

a special code for the COBOL program, 

Although the sample MCP (Figure 114) has an 
action code field which includes such a 
code in the section of comments immediately 
preceding the Mhl050 message handler, 13 
Figure 119 gives control to the STOP RUN 
statement only when there is no more data. 
This technique is acceptable for a COBOL 
program that receives a fixed amount of 
data, i.e., a program that is not 
continually looping waiting for data. 



Additional Interface Considerations 



The information that follows is a 
summary of miscellaneous recommendations 
and/or restrictions that apply to the 
communication oetween the message control 
program and the COBOL application program. 



T he_SEN D Statement: The COBOL source 1. 

statement causes data from the COBOL 
program to be placed in an output queue for 
subsequent transmission. Accordingly, when 
the outgoing message has beeji formatted, 
the sample SEND statement, (V) , transmits 
it to the output destination referred to by 
SYMDES. The end-of -message indicator (EMI) 
signals a complete message. The first 
sentence in the paragraph labeled 
"SEND-R0UTINE1" is "MOVE ' P2' TO SYMDES," 
so the data is sent to P2, 



The parameter DATE=YES must be coded 
in all input TPROCESS entries whose 
destination is a COBOL program and the 
parameter is also required in the PCB 
macro referenced oy the TPROCESS 
macro. Inclusion of this parameter 
causes the date and time of message 
entry to be placed in the MESSAGE DAT.;, 
and MESSAGE TIME clauses of the input 
CD (see "Communication Section" in the 
chapter entitled "Programming 
Techniques" > . 
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2. The RECDEL= parameter must be coded in 
the TPROCESS macro of the MCP if the 
COBOL programmer is to accept (via the 
RECEIVE statement) or transmit (via 
the SEND statement) data in SEGMENT 
mode. The user may either include in 
the incoming message the delimiter 
specified in this parameter or insert 
it via a MSGEDIT macro (see the 
section "Designing the Message 
Handler" in this chapter). 

3. The INITIATE macro cannot be used in a 
message handler for messages whose 
destination is a COBOL program. This 
macro would cause the MCP to transmit 
segments of a message to a destination 
queue before receiving the complete 
message. American National Standard 
COBOL, on the other hand, assumes that 
a complete message has been enqueued. 

4. American National Standard COBOL 
removes the last character of a 
message if it is X'37* (which is the 
EBCDIC representation for the EOT 
character). This is the last 
character of a message from a terminal 
that has been translated in the MH of 
the MCP via the CODE macro, or that is 
not processed in conversational mode 
(which would have been specified by 
coding CONV=YES in the STARTMH macro). 

5. An execution of the RECEIVE statement 
with the SEGMENT option results in the 
setting of the ESI (end of segment) 
indicator if end of segment is 
reached. When end of segment is also 
end of message, an end key of 2 
indicating EMI is given. If the last 
two characters in the message are an 
end segment indicator and the end of 
message character, the user will 
receive the indication first. Another 
RECEIVE will be necessary to receive 
the EMI indication. The RECEIVE from 
the EMI indication will set the TEXT 
LENGTH field of the input CD to zeros. 

6. For a message transmitted from a COBOL 
program to the location specified in 
the SYMBOLIC DESTINATION clause of an 
output CD, the FORWARD macro in the 
inheader subgroup of the MH for the 
COBOL program must specify DEST=PUT as 
its operand. 



following: operator control, error 
recovery, checkpoint/restart, message 
logging, debugging aids, and an on-line 
test feature. All of these TCAM aids are 
discussed in the publication IBM O S 
Teleco mmunications A ccess Method (ICfi.M) 
Programmer's G uide and Refere nce Manual . 
Some of these TCAM services have already 
been discussed in this chapter. This 
section briefly describes the operator 
control facility. 



OPERATOR CONTROL 



The TCAM operator control facility 
enables the user to examine or alter the 
status of a TP network simply by entering a 
series of specified operator commands. 
These commands may be entered from the 
system console or remote stations. 

Use of the operator control facility is 
made possible through operands of the INTRO 
and TERMINAL macros, discussed under "User 
Tasks" in this chapter. The INTRO macro 
contains an operand PRIMARY= that 
identifies the primary control station. 
The INTRO macro also specifies the single 
set of control characters that identify all 
operator commands. In the sample MCP shown 
in Figure 114 the INTRO command includes 
the PRIMARY=SYSCON operand, where SYSCON is 
the default, and the CONTROL=operand. 

Note: The CONTROL= operand is needed only 
when operator control messages are to be 
received from sources other than the system 
console. This operand is included in the 
example to show how it is specified. 

The MCP writer may specify a terminal 
name rather than SYSCON, provided that the 
terminal is on a nonswitched line and is 
able both to enter and to accept messages. 
If a station other than the system console 
is to be the primary operator station, 
"SECTERM=YES" must be specified in the 
station's TERMINAL macro. This operand of 
the TERMINAL macro is also used to specify 
other stations as secondary operator 
control stations. 

Operator command fields must be in the 
order indicated below and be separated from 
one another by at least one blank 
character. 



USING TCAM SERVICE FACILITIES 



TCAM allows for a variety of services in 
support of a COBOL teleprocessing system. 
Some of these services are provided 
automatically; others the user must 
specify. Some of the TCAM services are the 



control-chars operation operand 
[nextline] ending 

where: 

control-chars 

indicates a character string of 
one-to-eight nonblank characters 
identifying a command as an operand. 
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Note : The "control chars" field must 
be specified only with commands 
entered from a station and must not be 
specified in commands entered from the 
system console. 

operation 

indicates one of five operation types 
— HALT, HOLD, RELEASE, DISPLAY, and 
VARY — discussed under "Specifying 
Operator Commands". (There is also a 
MODIFY operation not discussed here. ) 



discussion of command formats is included 
under "Operator Control". 

For additional information about these 
and other possible operator commands, see 
the publication IBM_OS_Telecommunications 
Access Method (TCAM)_ programmer ' s guide_and 
Reference Manual. 



SYSCLOSE Command 



operand 

consists of one or more operands, the 
most commonly used of which are 
statname, address, grpname, and rln. 
These operands determine which 
functional operator command is 
associated with the operation t ype 
specified. (For some sample operands, 
see Table 32 in this chapter. ) 

[nextline] 

ensures that the reply will start on 
the next line. The "nextline" 
subfield must be followed immediately 
by the "ending" subfield. 

Note : The "nextline" subfield is 
specified only at terminals; it may 
not be used at the system console. 

ending 

indicates the end of a message and 
must be used by all sources entering 
an operator command. Depending on 
where the commands are being entered, 
TCAM has provided end-of-message 
signals as follows: 

• EOB, for system console 

• EOT, for start-stop stations 

• ETX/EOT, for BSC stations. 

These signals are further described in 
the publication IBM OS 
Telecommunic ation s Access Me thod 
(TCAM) Programmer's Guide and 
Reference Material. 



SPECIFYING OPERATOR COMMANDS 



Initiates either a quick or a flush 
closedown of the system. In a "quick" 
closedown, message traffic for each line is 
stopped as soon as any messages currently 
being sent or received have been completed 
In a "flush" closedown, incoming message 
traffic is suspended as in a quick 
closedown, and queued outgoing messages are 
sent to their destination before closedown 
is completed. 



SUSPXMIT Command 



Suspends transmission to a specified 
station. An intercepted station may still 
enter messages; only traffic to the station 
is suspended. 



RESMXIT Command 



Releases intercepted messages queued 
either for a specified station or for the 
line on which the specified station is 
located. 



INTRCEPT Command 



Requests display of all stations in the 
system that are intercepted (that is, those 
stations to which transmission has been 
suspended by a HOLD macro or a SUSXMIT 
operator command). 



Five sample operator commands that the 
COBOL TP user may want to use are the 
following: SYSCLOSE, SUSPXMIT, RESXMIT, 
INTRCEPT, and STARTLINE. These commands 
are described briefly below; their formats 
are given in Table 32. A general 



STARTLINE Command 



Causes transmission either to begin or 
to resume on a particular line (or all the 
lines) in a line group. 
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Table 32. Operator Command Formats 

r t t- 



Command 


i 


Control 


Characters j Operation 

- i - -L 


Operand 




| [nextline] ending 
. ± __ _ 


SYSCLOSE 


T 




t T 

| HALT |TP, QUICK 1 

| | FLUSH 

1 z | 




T 

| EOB 


SUSPXMIT 
RESMXIT 






| HOLD 

1 H 

| RELEASE 

1 A 


TP=statname 2 
TP=statname 2 




| EOB 
| EOB 


INTRCEPT 






| DISPLAY 
1 D 


TP, INTER 




| EOB 


STARTLINE 






1 VARY 

1 v 


(grpname, 3 rln Xt ) 
grpname 3 
address 5 


,ONTP 


| EOB 



1 X X X 

Notes; 

1. The user selects either QUICK or FLUSH, depending on the type of closedown desired. 

2. The replacement for "statname" should be the name of the TERMINAL macro. 

3. The "grpname" field should be the same as the DDNAME=operand field of the DCB for 
the line group. 

4. The "rln" field should contain the relative line number of the line within the 
group. 

5. The address is the physical line number. 

L J 
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MACHINE CONSIDERATIONS 



This chapter contains information 
concerning system requirements for the 
COBOL compiler, execution time, and the 
sort feature. Additional information for 
use in estimating the main and auxiliary 
storage requirements is contained in the 
publication IB M OS Fu ll Ame ric an National 
c ''" ^nda^d '"'OB'^L Compiler and Librar" 
Version 4, Installation Reference Material. 



data extent block. Such action 
often results in either an 80A 
abnormal termination, if the space 
limitations are encountered when 
an attempt is made to load a 
compiler phase, or diagnostic 
message IKF0020I-D, if more 
extensive co"*"e has to oe allocated 
for table space for compiler 
processing. 



MINIMUM MACHINE REQUIREMENTS FOR THE COBOL 
COMPILER 



The oasic system requirements for use of 
the COBOL compiler are: 

• A System/360 (at least a Model 40 ) or a 
System/370 model 1 , with a minimum of 
80K (81,920) bytes of main storage 
available to the compiler, and the 
standard and decimal instruction sets. 
The floating-point instruction set is 
required if floating-point data items 
and f r act ional- ^exponents are used i n 
the program. 

At least 80K (81,920) bytes should 
be allocated in the SIZE option of the 
EXEC job control card that requests 
execution of the compiler. If less 
than this is specified, the system 
assumes the default value of 80K. If 
more storage is allocated, the compiler 
will run more efficiently. 

Notes: Before deciding on a value for 
the SIZE option, the programmer should 
consider all of the following: 

1. The value of compiler data set 
SPACE parameters. Given limited 
storage under MFT, if the primary 
space allocation for compiler data 
sets is too small and secondary 
extents are needed, the system 
must often use the compiler 
xiiiiCayc area i_or tue respective 



*A System/370 model may be substituted for 
a System/360 model for compilation 
regardless of other considerations. If, 
however, IBM-370 is specified as the 
computer-name in the OBJECT-COMPUTER 
paragraph, a System/370 model must be used 
for object program execution. 



2. The size and/or complexity of the 
program to be compiled. A large 
or complex program requires more 
table space than a small or simple 
one. Accordingly, this table 
space must be reflected in the 
SIZE parameter chosen. (For 
further discussion of table 
requirements, see "Table Handling 
Considerations. ") 

3. The blocking factors used for 
compiler data sets. The SIZE 
parameter (and BUF parameter) 

-ref-l-eet-- the increased -buff er size 
needed to handle blocked compiler 
data sets. 



• Compiler Work Files — Five utility 
data sets named SYSUTl, SYSUT2, SYSUT3, 
SYSUT4. and SYSUT5 (if the SYMDMP 
option is specified) . At least one 
mass storage device, such as an IBM 
2311 Disk Storage Drive, for residence 
of the operating system and SYSUTl. 
Both the operating system and SYSUTl 
may reside on the same volume. The 
data sets SYSUT2, SYSUT3, SYSUT4, and 
SYSUT5 (if the SYMDMP option is 
specified) can reside on tape or on 
mass storage. If they reside on tape, 
there must be a tape volume for each 
data set. If they reside on mass 
storage, there must be enough space on 
the volume to accommodate the data 
sets. 

• A device, such as the 1052 
Printer-Keyboard, for direct operator 
communication. 

• A device, such as a card reader or a 
tape unit, for the job input stream. 

« A printer or tape unit for the system 
output file. 
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MULTIPROGRAMMING WITH A VARIABLE NUMBER OF 
TASKS (MVT) 



REGION Parameter 



COMPI LAT ION: If the compiler is being 
executed under the MVT option of OS, the 
REGION parameter, specified as 80K bytes in 
the COBUC and COBUCLG cataloged procedures, 
becomes significant (see the section "Using 
the Cataloged Procedures"). If the 
programmer wishes to override this value, 
he can specify a region size in either the 
JOB statement or in the EXEC statement of 
the compiler. The size specified should 
not be less than the value of SIZE in the 
PARM field of the EXEC statement. 



double buffered if no blocking factor 
is specified) . 

3. The size of tne data management 
routines and control blocks that are 
used (see the publication 1BM_0S 
Storage E st i mates ) . 

4. Any GETMAIN macro instruction executed 
for USE LABELS, etc. 

5. An additional 4K bytes. 

b. If the Sort feature is used, 15, 3b0 

bytes plus any additional core storage 
assigned via the SORT-CORE-SIZE 
special register. 



The following examples illustrate both 
the default and the override cases: 



Intermediate Data Sets under MVT 



Example 1 

//J0B1 
//STEP1 



JOB 
EXEC 



1234, J. SMITH 
COBUC 



In this example, the programmer 
accepts the REGION default value of 
80K specified in the COBUC cataloged 
procedure. 



Example 2 

//JOB2 

//STEP1 

// 



JOB 1234, J.SMITH 
EXEC COBUCLG, REGION=128K, X 
PARM. COB= l SIZE^ISOOOO 1 



In this example, the REGION default 
value is overridden. Rounding 130000 
to the next highest 2K multiple, it 
becomes 131072, or 128K. 

EXECUTION: Priority schedulers require 
that tne REGION parameter be specified for 
execution of object programs, unless the 
programmer is willing to accept default 
region size. The default value is 
established in the input reader procedure. 
The region size needed for the execution of 
the object program is the sum of the 
following values: 

1. The size of the object module after it 
has been link-edited with all of the 
necessary object time subroutines. 

2. The size of the input/output buffers 
being used, multiplied by the blocking 
factor (standard sequential files are 



Except when the Direct Sysout Writer is 
used, SYSIN and SYSOUT data resides in 
intermediate direct-access data sets. 
These data sets are used by the system to 
temporarily hold all of the job' s input anJ 
output data. 

§XSI N-S YSOUT_CHARACTERISTIC3 : Ihe input 
and output data set characteristics are 
determined by the system, but can be 
altered by the programmer if necessary. 
Tne procedure used to alter the default 
values depends on whether the data set is 
for input or output, as follows: 

• F or SYSIN data — the programmer must 
request, at the time the job is 
submitted, that the operator use one of 
the several reader procedures 
available. Reader procedures are 
cataloged procedures that control the 
reader and vary according to the 
blocking factor specified. 

• F or SYSOU T d ata — the programmer must 
use override statements as described in 
"Using the Cataloged Procedures. " 

Output is placed in the SYSOUT 
intermediate data set, except when the 
Direct SYSOUT Writer is used, in wnich case 
output goes directly to the printer, punch, 
or tape as in systems with the primary 
control program. Since nothing is written 
out until the completion of the job, the 
programmer must make sure that the SZSOUT 
data set is large enough to hold all of the 
possible output data of his program. The 
SPACE parameter of the DD statement is 
specified for SYSOUT with a specified 
default value. If the programmer 
determines that his output will exceed the 
default value, he can do either or botn of 
two things: 
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1. Specify blocking of his data set with 
the DCB parameter of an override DD 
statement 



The total space required for object-time 
debugging should be calculated as follows: 



2. Override the compilation step of a 
compiled procedure by specifying the 
SPACE parameter. An example of a 
statement that can be used is: 

//COB.SYSPRINT DD SPACE=(121, (500 # 50) ) 



S = S + [S ] + STN 

TS DBG FLW 

S 
S¥MDMP 



Note : If the TRK or CYL subparameters of 
the SPACE parameter are used, the 
programmer should be aware that requests 
will differ depending upon the mass storage 
device used (2301, 2303, 2311, ..., etc). 
To avoid this consideration! the average 
record-length subparameter can be used. 



MULTIPLE OPEN AND CLOSE STATEMENTS: Under 
the MVT control program, input data 
following the DD * or DD DATA card becomes 
a single data set. Once a CLOSE statement 
is encountered. The data set is 
repositioned to the beginning of the data 
set. To avoid errors, the programmer 
should keep this in mind when using more 
than one OPEN and CLOSE statement for a 
data set assigned to SYSIN. 



| where: 



Note: Under MVT, a file must be closed 
before the STOP RUN or EXIT PROGRAM 
statement is executed. Failure to do this 
results in an abnormal termination. 



TS 



DBG 



FLW 



STN 



= the total space 



= the space allocated once and 
only once for a run containing 
any object-time debugging 
options 



= the space required for the FLOW 
option 



= the space required for the 
STATE option 



[ SYMDMP- ■ -=- the space required _f.or_.t_he J 

I SYMDMP option | 

l J 



S = 3700 bytes 
DBG 



EXECUTION TIME CONSIDERATIONS 



S =(1672 + 4*nn + 10*P) bytes 
FLW 



The amount of main storage must be 
sufficient to accommodate at least: 

• The control program 

• Data management support 

• The load module to be executed 

When the OPTIMIZE option is specified, 
the number of procedure blocks in the 
program cannot exceed 255. A procedure 
block is approximately 4096 bytes of 
Procedure Division code. 

COBOL programs compiled with any of the 
symbolic debugging options (STATE, FLOW, 
SYMDMP) have execution time requirements 
that differ from those of similar programs 
compiled without these options. If the 
SYMDMP option is in effect, the data set it 
required at compile time (SYSUT5) must be 
present at execution time. 



where 

nn = the number specified in the 

FLOW=nn parameter of the EXEC 
job control statement 

P = the total number of 

paragraph- names in a COBOL 
program 

S =(1090 + 5*V) bytes 
STN 

where 

V = the number of verbs in the 

COBOL program la number that 
is approximately equal to the 
number of statements in the 
program) 

S =(11250 + S +S )oytes 
SYMDMP TABLES DM 
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where 

S 
TABLES = the size of tables for SYMDMP 



DM = the size of data management 
required for SYMDMP 
l j 

S =(72*PC+[19*LC+[8*ON]+7*id]+[S ]) bytes 
TABLES ODOTAB 

where 

PC = the number of program control 
cards 



QSAM = 1424 bytes = the space 

required for QSAM modules (wnen 
not on the LPA) and no QSAM files 
are used in the program 

The input/output device requirements for 
execution of the problem program are 
determined from specifications made in the 
Environment Division of the source program 



Note ; An IBM System/370 is required for 
execution if IBM-370 is specified as the 
computer-name with OBJECT- COMPUTER 
paragraph of the Configuration Section. 



LC = the number of line control cards 



ON = the number of line control cards 
with ON options 

id = the number of identifiers 

requested on line-control cards 



ODOTAB = the size of ODOTAB on the 
debug file (approximately 27 
times the number of unique 
Objects Of OCCURS DEPENDING ON 
statements) . 

S =(818+S + [S ])bytes 

DM BSAM QSAM 

where 

S 
BSAM = 800 bytes = the space required 
for BSAM modules (when not in the 
LPA) 



SORT FEATURE CONSIDERATIONS 



The basic requirements for use of the 
Sort feature are: 

• A System/360 model or System/370 with 
sufficient main storage to accommodate 
the load module to be executed plus a 
minimum of 15,360 bytes for execution 
of the sort program and any additional 
core storage assigned to the sort 
program via the SORT-CORE-SIZE special 
register. 

• At least one mass storage device (which 
may be the system residence device) for 
residence of SYS1. SORTLIB. 

• At least three tape units or one mass 
storage device for intermediate 
storage. 
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APPENDIX A: SAMPLE PROGRAM OUTPUT 



The following is a sample COBOL program 
and the output listing resulting from its 
compilation, linkage editing, and 
execution. The program creates a blocked, 
unlabeled, standard seguential file, writes 
it out on tape, and then reads it back in. 
It also does a check on the field called 
NO-OP-DEPENDENTS* All data records in the 
file are displayed. Those with a zero in 
the NO-OF-DEPENDENTS field are displayed 
with the special character Z. The records 
of the file are not altered from the time 



of 'creation, despite the fact that the 
NO-OF-DEPENDENTS field is changed for 
display purposes. The individual records 
of the file are created using the 
subscripting technique. TRACE is used as 
debugging aid during program execution. 

The output formats illustrated in the 
listing are described in "Output. " 
Individual parts of the listing are 
numbered in accordance with tne numbers 
used in the chapter "Output. " 



00001 


100010 


00002 


100020 


00003 


100030 


00004 


100040 


00005 


100050 


00006 


100060 


00007 


100070 


00008 


100080 


00009 


100090 


00010 


100100 


00011 


100110 


00012 


100120 


00013 


100130 


00014 


100140 


00015 


100150 


00016 


100160 


00017 


100170 


00018 


100180 


00019 


100190 


00020 


100200 


00021 


100210 


00022 


100220 


00023 


100225 


00024 


100230 


00025 


100240 


0002b 


100250 


00027 


100260 


00028 


100270 


00029 


100280 


00030 


100290 


00031 


100300 


00032 


100310 


00033 


100320 


00034 


100330 


00035 


100340 


00036 


100350 


00037 


100360 


00038 


100370 


00039 


100375 


00040 


** 00380 


00041 


100395 


00042 


100405 


00043 


100410- 


00044 


100420 


00045 


100440 


00046 


100450 


00047 


100460 


00048 


100470 


00049 


100480 


00050 


100490 


00051 


100500 


00052 


100510 


00053 


100520 


00054 


100522 



IDENTIFICATION DIVISION. 
PROGRAM-ID. TESTRJN. 

AUTHOR. PROGRAMMER NAME. 

INSTALLATION. NEW YORK PROGRAMMING CENTER. 

DATE-WRITTEN. JULY 12 f 1968. 
DATE -COMPILED. FEB 19,1972 



00900008 
00900010 
00900012 
00900014 
00900016 
00900018 



REMARKS. THIS PROGRAM HAS BEEN WRITTEN AS A SAMPLE PROGRAM FOR 00900020 



IT CREATES AN OUTPUT FILE AND READS IT BACK AS 



00900022 
00900024 
00900026 
00900028 
00900030 
00900032 
00900034 
0-0-9-&0-036- 
00900038 
00900040 
00900042 
00900044 
00900046 
00900048 
00900050 



COBOL USERS 
INPUT. 
ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 

SOURCE-COMPUTER. IBM-360-H50. 
OBJECT- COMPUTER. IBM-360-H50. 
INPUT-OUTPUT SECTION. 
FILE-CONTROL. 

SELECT FILE-1 ASSIGN TO UT- 2400-S-SAMPLE. 

SELECT FILE-2 ASSIGN TO UT-2400-S-SAMPLE. 
DATA DIVISION. 
FILE SECTION. 
FD FILE-1 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 100 CHARACTERS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MODE IS F 

DATA RECORD IS RECORD-1. 
01 RECORD-1. 

02 FIELD-A PICTURE IS X(20). 
FD FILE-2 

LABEL RECORDS ARE OMITTED 

BLOCK CONTAINS 5 RECORDS 

RECORD CONTAINS 20 CHARACTERS 

RECORDING MODE IS F 

DATA RECORD IS RECORD-2. 
01 RECORD-2. 

02 FIELD-A PICTURE IS X(20). 
WORKING-STORAGE SECTION. 

77 KOUNT PICTURE S99 COMP SYNC. 

77 NOMBER PICTURE S99 COMP SYNC. 
01 FILLER. 

02 ALPHABET PICTURE X(26) VALUE "ABCDEFGHI JKLMNOPQRSTUVWXYZ 

02 ALPHA REDEFINES ALPHABET PICTURE X OCCURS 26 TIMES. 

02 DEPENDENTS PICTURE X(26) VALUE "012340123401234012340123400900088 

"0"= 00900090 

2 DEPEND REDEFINES DEPENDENTS PICTURE X OCCURS 26 TIMES. 
01 WORK-RECORD. 

2 NAME- FIELD PICTURE X. 

02 FILLER PICTURE X VALUE SPACE. 

02 RECORD- NO PICTURE 9999. 

02 FILLER PICTURE X VALUE SPACE. 

02 LOCATION PICTURE AAA VALUE "NYC". 

02 FILLER PICTURE X VALUE SPACE. 

02 NO-OF-DEPENDENTS PICTURE XX. 

02 FILLER PICTURE X(7) VALUE SPACES. 
01 RECORDA. 



09 00052 
00900054 
00900056 
00900058 
00900060 
00900062 
00900064 
00900066 
009000b8 
00900070 
00900072 
00900074 
00900076 

00900080 
00900082 
00900084 
00900086 



00900092 
00900094 
00900096 
00900098 
00900100 
00900102 
00900104 
00900106 
00900108 
00900110 
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00055 


100524 


00056 


100526 


00057 


100530 


00058 


100540 


00059 


100550 


00060 


100560 


00061 


100570 


00062 


100580 


00063 


100590 


00064 


100600 


OO065 


100610 


00066 


100620 


00067 


100625 


00068 


100630 


00069 


100640 


00070 


100650 


00071 


100660 


00072 


100670 


00073 


100680 


00074 


100690 


00075 


100700 


00076 


100710 


00077 


100720 


00078 


100730 


00079 


100740 


00080 


100750 


00081 


100760 


00082 


100770 


00083 


100780 


00084 


**xx 



02 A PICTURE S9(4) VALUE 1234. 

02 B REDEFINES A PICTURE S9<7) COMPUTATIONAL- 3. 
PROCEDURE DIVISION. 
BEGIN. READY TRACE. 

NOTE THAT THE FOLLOWING OPENS THE OUTPUT FILE TO BE CREATED 

AND INITIALIZES COUNTERS. 
STEP-1. OPEN OUTPUT FILE-1. MOVE ZERO TO KOUNT NOMBER. 

NOTE THAT THE FOLLOWING CREATES INTERNALLY THE RECORDS TO BE 

CONTAINED IN THE FILE, WRITES THEM ON TAPE, AND DISPLAYS 

THEM ON THE CONSOLE. 
STEP-2* ADD 1 TO KOUNT, ADD 1 TO NOMBER, MOVE ALPHA (KOUNT) TO 

NAME-FIELD. 

COMPUTE B = B + 1. 

MOVE DEPEND (KOUNT) TO NO-OF-DEPENDENTS. 

MOVE NOMBER TO RECORD-NO. 
STEP- 3. DISPLAY WORK- RECORD UPON CONSOLE. WRITE RECORD-1 FROM 

WORK-RECORD. 
STEP-4. PERFORM STEP-2 THRU STEP-3 UNTIL KOUNT IS EQUAL TO 26. 

NOTE THAT THE FOLLOWING CLOSES OUTPUT AND REOPENS IT AS 

INPUT. 
STEP-5. CLOSE FILE-1. OPEN INPUT FILE-2. 

NOTE THAT THE FOLLOWING READS BACK THE FILE AND SINGLES OUT 

EMPLOYEES WITH NO DEPENDENTS. 
STEP-6. READ FILE-2 RECORD INTO WORK-RECORD AT END GO TO STEP- 8. 
STEP-7. IF NO-OF-DEPENDENTS IS EQUAL TO "0" MOVE " Z" TO 

NO-OF-DEPENDENTS. EXHIBIT NAMED WORK-RECORD. GO TO 

STEP-6. 
STEP-8. CLOSE FILE-2. 

STOP RUN. 



00900112 
00900114 
00900116 
00900118 

00900122 
00900124 
00900126 

00900130 



00900134 
00900136 
00900138 

00900142 
00900144 
00900146 
00900148 
00900150 
00900152 
00900154 
00900156 
00900158 
00900160 
00900162 
00900164 



INTRNL NAME 

DNM=1-148 

DNM= 1-167 

DNM=1-188 

DNM= 1-205 

DNM=l-224 

DNM=l-245 

DNM=l-265 

DNM=l-280 

DNM=l-296 

DNM=1-310 

DNM=l-328 

DNM=l-346 

DNM=l-366 

DNM=l-382 

DNM=l-406 

DNM=l-4 26 

DNM=l-440 

DNM=l-459 

DNM=l-473 

DNM=1-491 

DNM=2-000 

DNM=2-026 

DNM=2-040 

DNM=2-060 

DNM=2-071 



LVL SOURCE NAME 

FD FILE-1 

01 RECORD-1 

02 FIELD-A 
FD FILE-2 

01 RECORD- 2 

02 FIELD-A 
77 KOUNT 
77 NOMBER 

01 FILLER 

02 ALPHABET 
02 ALPHA 

02 DEPENDENTS 

02 DEPEND 

01 WORK-RECORD 

02 NAME-FIELD 
02 FILLER 

02 RECORD- NO 

02 FILLER 

02 LOCATION 

02 FILLER 

02 NO-OF-DEPENDENTS 

02 FILLER 

01 RECORDA 

02 A 
02 B 



BASE 


DISPL 


INTRNL NAME 


DEFINITION 


USAGE 


R O Q M 


DCB=01 




DNM=1-148 






QSAM 




F 


BL=1 


000 


DNM=1-167 


DS 


0CL20 


GROUP 






BL=1 


000 


DNM=1-188 


DS 


20C 


DISP 






DCB=0 2 




DNM=l-205 






QSAM 




F 


BL=2 


000 


DNM= 1-224 


DS 


0CL20 


GROUP 






BL=2 


000 


DNM=l-245 


DS 


20C 


DISP 






BL=3 


000 


DNM=l-265 


DS 


1H 


COMP 






BL=3 


002 


DNM=l-280 


DS 


1H 


COMP 






BL=3 


008 


DNM= 1-296 


DS 


0CL52 


GROUP 






BL=3 


008 


DNM=1-310 


DS 


26C 


DISP 






BL=3 


008 


DNM=l-328 


DS 


1C 


DISP 


R O 




BL=3 


022 


DNM=l-346 


DS 


26C 


DISP 






BL=3 


022 


DNM= 1-366 


DS 


1C 


DISP 


R O 




BL=3 


040 


DNM=l-38 2 


DS 


OCL20 


GROUP 






BL=3 


040 


DNM= 1-406 


DS 


1C 


DISP 






BL=3 


041 


DNM=l-4 26 


DS 


1C 


DISP 






BL=3 


042 


DNM=l-440 


DS 


4C 


DISP-NM 






BL=3 


046 


DNM=l-459 


DS 


1C 


DISP 






BL=3 


047 


DNM=l-473 


DS 


3C 


DISP 






BL=3 


04A 


DNM=1-4 91 


DS 


1C 


DISP 






BL=3 


04B 


DNM=2-000 


DS 


2C 


DISP 






BL=3 


4D 


DNM=2-026 


DS 


7C 


DISP 






BL=3 


058 


DNM=2-040 


DS 


0CL4 


GROUP 






BL=3 


058 


DNM=2-060 


DS 


4C 


DISP-NM 






BL=3 


058 


DNM=2-071 


DS 


4P 


COMP- 3 


R 





384 



'.£,nUM VU\f 



TGT 



00248 



SAVE AREA 

SWITCH 

TALLY 

SORT, SAVE 

ENTRY- SAVE 

SORT CORE SIZE 

RET CODE 

SORT RET 

WORKING CELLS 

SORT FILE SIZE 

SORT MODE SIZE 

PGT-VN TBL 

TGT-VN TBL 

VCONPTR 

LENGTH OF VN TBL 

LABEL RET 

CURRENT PRIORITY 

DBG R14SAVE 

COBOL INDICATOR 

A(INITl) 

DEBUG TABLE PTR 

SUBCOM PTR 

SORT DDNAME 

UNUSED 

DBG R11SAVE 

UNUSED 

PRBL1 CELL PTR 

GENCBTBL PTR 

UNUSED 

TA LENGTH 

UNUSED 

OVERFLOW CELLS 

BL CELLS 

DECBADR CELLS 

TEMP STORAGE 

TEMP STORAGE- 2 

TEMP STORAGE- 3 

TEMP STORAGE- 4 

BLL CEXLS 

VLC CELLS 

SBL CELLS 

INDEX CELLS 

SUBADR CELLS 

ONCTL CELLS 

PFMCTL CELLS 

PFMSAV CELLS 

VN CELLS 

SAVE AREA =2 

SAVE AREA =3 

XSASW CELLS 

XSA CELLS 



00248 
00290 
00294 
00298 
0029C 
002A0 
002A4 
002A6 
002A8 
003D8 
003DC 
003E0 
003E4 
003E8 
3 EC 
00 3EE 
003EF 
003F0 
003F4 
003F8 
003FC 
00400 
00404 
0040C 
00420 
00424 
00428 
0042C 
00430 
00431 
00434 
0043C 
0043C 
00448 
00450 
00458 
00458 
00458 
DW5S'" 
00460 
00460 
00460 
00460 
00468 
00468 
00468 
0046C 
00470 
00470 
00478 
00478 
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LITE ?. h L Poni . IKf'Xl 

004F0 (LIT+0) 00030001 1C00001A 004805EF 48000000 C0000000 

DISPLAY LITERALS (BCD) 
00504 (LTL+20) 'WORK-RECORD' 



PG1 

OVERFLOW CELLS 
VIRTUAL CELLS 
PROCEDURE NAME CELLS 
GENERATED NAME CELLS 
DCB ADDRESS CELLS 
VNI CELLS 
LITERALS 
DISPLAY LITERALS 



00498 

00498 
00498 
004 B8 
004CC 
004E4 
004EC 
004F0 
00504 



REGISTER ASSIGNM'i'JT 



REG b 


BL 


-3 


REG 7 


BL 


= 1 


REG 8 


BL 


= 2 



WORKING-STORAGE STARTS AT LOCATION 00088 FOR A LENGTH OF 00060. J 



58 



VERB 



58 
61 



VERB 



61 



VERB 



000510 
000510 
000512 
000516 
000518 
00051C 
00051E 
000522 
000526 
000528 
00052B 



000536 
00053A 
00053C 
000540 
000542 
000546 
00054A 
00054C 
00054F 

000556 
00055A 



START 



07 00 

58 F0 C 00C 

05 EF 

58 F0 C 010 

05 IF 

0000003A 

58 FO C 014 

05 IF 

000140 

05F5F840404040 



000532 96 40 D 048 



58 FO C 00C 

05 EF 

58 FO C 010 

5 IF 

0000003D 

58 FO C 014 

05 IF 

000140 

05F6F140404040 

58 FO C 00C 
5 EF 



EQU 


* 




BCR 


0,0 




L 


15, OOC(0, 12) 


V(ILBODBG4) 


BALR 


14,15 




L 


15,010(0, 12) 


V(ILEOFLWl) 


BALR 


1,15 




DC 


X'0000003A« 




L 


15,014(0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X'000140' 




DC 


X'05F5F840404040' 




01 


048(13), X' 40" 


SWT+0 


L 


15, 00C(0,12) 


V(ILBODBG4) 


BALR 


14,15 




L 


15, 010(0, 12) 


V(ILBOFLWl) 


BALR 


1,15 




DC 


X'0000003D' 




L 


15,014(0,12) 


V(ILBODSPO) 


BALR 


1, 15 




DC 


X'000140' 




DC 


X'05F6F140404040' 




L 


15,00C(0, 12) 


V(ILBODBG4) 


BALR 


14,15 





386 



VERB 



65 



65 



65 



VERB 



67 
68 



VERB 
VERB 



10 



11 



69 



70 



VERB 12 



VERB 13 



0G055C 


58 


10 


C 


4C 




000560 


D2 


03 


D 


060 C 


018 


000566 


D2 


02 


1 


039 D 


061 


00056C 


58 


10 


C 


04C 




000570 


02 


01 


1 


032 C 


060 


000576 


D2 


01 


1 


060 C 


062 


00057C 


50 


10 


D 


228 




000580 


92 


8F 


D 


228 




000584 


41 


10 


D 


228 




000588 


OA 


13 








00058A 


58 


10 


C 


4C 




00058E 


18 


21 








000590 


58 


FO 


1 


030 




000594 


05 


EF 








000596 


50 


10 


D 


1F4 




00059A 


58 


70 


D 


1F4 




00059E 


D2 


01 


6 


000 C 


058 


0005A4 


D2 


01 


6 


002 C 


058 


0005AA 












0005AA 


58 


FO 


C 


OOC 




0005AE 


05 


EF 








0005BO 


58 


FO 


C 


010 




0005B4 


05 


IF 








0005B6 


00000041 




0005BA 


58 


FO 


c 


014 




0005BE 


05 


IF 








0005C0 


000140 






0005C3 


05F6F540404040 


0005CA 


48 


30 


c 


05A 




0005CE 


4A 


30 


6 


000 




0005D2 


40 


30 


6 


000 




0005D6 


48 


30 


C 


05A 




0005DA 


4A 


30 


6 


002 




0005DE 


40 


30 


6 


002 




0005E2 


41 


40 


6 


008 




0005E6 


48 


20 


6 


000 




0005EA 


4C 


20 


C 


05A 




O-0^5EE 


1A 


**2 








0005FO 


5B 


40 


C 


058 




0005F4 


50 


40 


D 


218 




0005F8 


58 


EO 


D 


218 




0005FC 


D2 


00 


b 


040 E 


000 


000602 


FA 


30 


6 


058 C 


05C 


000608 


41 


40 


6 


022 




OOOSOC 


48 


20 


6 


000 




000610 


4C 


20 


C 


05A 




000614 


1A 


42 








000616 


5B 


40 


C 


058 




00061A 


50 


40 


D 


21C 




00061E 


58 


EO 


D 


21C 




000622 


D2 


00 


6 


04B E 


000 


000628 


92 


40 


6 


04C 




00062C 


48 


30 


6 


002 




000630 


4E 


30 


D 


208 




000634 


F3 


31 


6 


042 D 


20E 


00063A 


96 


FO 


6 


045 




00063E 


58 


FO 


C 


OOC 




000642 


05 


EF 








000644 


58 


FO 


C 


010 




000648 


05 


IF 








00064A 


00000046 




00064E 


58 


FO 


C 


014 




000652 


05 


IF 








000654 


00014C 


) 






000657 


05F7F04040404C 


) 



PN=01 



L 


1.04C(0.12) 


DCB=1 




MVC 


060(4, 13), 018(12) 


WC = 01 


v(ilbolrr: 


MVC 


039*3,1) ,061(13) 




WC=0 2 


L 


1, 04C(0, 12) 


DCB=1 




MVC 


032(2,1) ,060(12) 




LIT+8 


MVC 


060(2, 1), 062(12) 




LIT+10 


ST 


1,228(0,13) 


SAV3 




MVI 


228(13), X' 8F' 


SAV3 




LA 


1,228(0,13) 


SAV3 




SVC 


19 






L 


1,04C(0,12) 


DCB=1 




LR 


2,1 






L 


15,030(0,1) 






BALR 


14, 15 






ST 


1,1F4(0,13) 


BL =1 




L 


7, 1F4(0, 13) 


BL =1 




MVC 


000(2, 6), 058(12) 


DNM=l-265 


LIT+0 


MVC 


002(2,6) ,058 (12) 


DNM=l-280 


LIT+0 


EQU 


* 






L 


15, 00C(0, 12) 


V(ILBODBGU) 




BALR 


14,15 






L 


15,010(0, 12) 


V(ILBOFLWl) 




BALR 


1,15 






DC 


X'00000041' 






L 


15,014(0,12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X' 000140' 






DC 


X'05F6F540404040' 






LH 


3, 05A(0, 12) 


LIT+2 




AH 


3,000(0,6) 


DNM=l-265 




STH 


3,000(0, 6) 


DNM=l-265 




LH 


3,05A(0, 12) 


LIT+2 




AH 


3,002(0,6) 


DNM=l-280 




STH 


3,002(0, 6) 


DNM=l-28 




LA 


4,008(0, 6) 


DNM=l-328 




LH 


2,000(0,6) 


DNM=l-265 




MH 


2,05A(0, 12) 


LIT+2 




AR 


*.-2 






S 


4,058(0,12) 


LIT+0 




ST 


4,218(0,13) 


SBS=1 




L 


14, 218(0, 13) 


SBS=1 




MVC 


040(1,6) ,000(14) 


DNM=l-406 


DNM=l-328 


AP 


058(4,6) ,05C(1,12) 


DNM=2-71 


LIT+4 


LA 


4,022(0,6) 


DNM=l-366 




L u 


2, 000(0, 6) 


njjj4=l-265 




MH 


2,05A(0,12) 


LIT+2 




AR 


«.2 






S 


4,058(0,12) 


LIT+0 




ST 


4, 21C(0, 13) 


SBS=2 




L 


14,21C(0,13) 


S8S=2 




MVC 


04B(1,6) ,000(14) 


DNM=2-0 


DNM= 1-366 


MVI 


04C(6),X , 40* 


DNM=2-0+l 




LH 


3, 002(0, 6) 


DNM=l-280 




CVD 


3,208(0,13) 


TS=01 




UNPK 


042(4, 6), 20E(2, 13) 


DNM=l-440 


TS=07 


01 


045(6) ,X'F0' 


DNM=l-440+3 




L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14, 15 






L 


15,010(0,12) 


V ( ILBOFLW1 ) 




BALR 


1,15 






DC 


X' 00000046' 






L 


15,014(0, 12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X , 000140' 






DC 


X'05F7F040404040' 
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70 



VERB 11 



70 



VERB 15 



72 



VERB 16 



72 



VERB 17 



7b 



VERB IB 



75 



VERB 19 



00065E 


58 


FO 


C 


ooc 


000662 


05 


EF 






000664 


58 


FO 


C 


014 


000668 


05 


IF 






00066A 


0002 






00066C 


00 








00066D 


000014 




000670 


0D0001FC 


000674 


0040 






000676 


FFFF 






000678 


58 


FO 


C 


OOC 


00067C 


05 


EF 






00067E 


D2 


13 


7 


000 6 I 


000684 


58 


10 


C 


04C 


000688 


18 


21 






00068A 


58 


10 


C 


04C 


00068E 


58 


00 


1 


04C 


000692 


58 


FO 


1 


030 


000696 


44 


00 


1 


060 


00069A 


50 


10 


D 


1F4 


00069E 


58 


70 


D 


1F4 


0006A2 










0006A2 


58 


10 


D 


224 


0006A6 


07 


Fl 






0006A8 










0006A8 


07 


00 






0006AA 


58 


FO 


C 


OOC 


0006AE 


05 


EF 






0006B0 


58 


FO 


C 


010 


0006B4 


05 


IF 






0006B6 


00000048 


0006BA 


58 


FO 


c 


014 


0006BE 


05 


IF 






0006C0 


000140 




0006C3 


05F7F240404040 


0006CA 


58 


00 


D 


224 


0006CE 


50 


00 


D 


220 


0006D2 


58 


00 


C 


03S 


0006D6 


50 


00 


D 


224 


0006DA 










0006DA 


48 


30 


6 


000 


0006DE 


49 


30 


C 


05E 


0006E2 


58 


FO 


c 


3C 


0006E6 


07 


8F 






0006E8 


58 


10 


c 


020 


0006EC 


07 


Fl 






0006EE 










0006EE 


58 


00 


D 


220 


0006F2 


50 


00 


D 


224 


0006Fb 


58 


FO 


C 


OOC 


OOObFA 


05 


EF 






00 06FC 


58 


FO 


C 


010 


000700 


05 


IF 






000702 


0000004B 


000706 


58 


FO 


C 


014 


00070A 


05 


IF 






00070C 


000140 




00070F 


05F7F540404040 


000716 


58 


FO 


C 


OOC 


00071A 


05 


EF 






00071C 


58 


10 


C 


04C 


000720 


58 


30 


1 


02C 


000724 


91 


OF 


3 


OOC 


000728 


05 


50 







040 



GN=01 



PN=02 



GN=02 



GN=03 



L 


15,0OC(0,12) 


V(ILBODBG4) 




BALR 


14, 15 






L 


15,014(0,12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X'0002' 






DC 


X'OO* 






DC 


X' 000014' 






DC 


X'ODOOOIFC 


BL =3 




DC 


X'0040' 






™C 


V ■ PCTPlM 








" * *■ * *■ 






L 


15,00C(0, 12) 


V(ILBODBG4) 




BALR 


14,15 






MVC 


000(20,7), 040(6) 


DNM=1-167 


DNM=l-38 2 


L 


1,04C(0,12) 


DCB=1 




LR 


2,1 






L 


1, 04C(0,12) 


DCB=1 




L 


0,04C(0,1) 






L 


15,030(0,1) 






EX 


0,060(0,1) 






ST 


1,1F4(0,13) 


BL =1 




L 


7,1F4(0, 13) 


BL =1 




EQU 


* 






L 


1, 224(0,13) 


VN=01 




BCR 


15,1 






EQU 


* 






BCR 


0,0 






L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14,15 






L 


15,010(0,12) 


V(ILBOFLWl) 




BALR 


1,15 






DC 


X'00000048' 






L 


15,014(0,12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X , 000140 t 






DC 


X'05F7F240404040' 






L 


0,224(0,13) 


VN=01 




ST 


0,220(0,13) 


PSV=1 




L 


0,038(0, 12) 


GN=02 




ST 


0,224 (0,13) 


VN=01 




EQU 


* 






LH 


3, 000(0,6) 


DNM=l-265 




CH 


3,05E(0, 12) 


LIT+6 




L 


15,03C(0,12) 


GN=0 3 




BCR 


8, 15 






L 


1,020(0,12) 


PN=01 




BCR 


15, 1 






EQU 


* 






L 


0, 220(0, 13) 


PSV=1 




ST 


0,224 (0,13) 


VN=01 




L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14, 15 






L 


15,010(0,12) 


V(ILBOFLWl) 




BALR 


1, 15 






DC 


X'0000004B' 






L 


15,014(0, 12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X'000140' 






DC 


X'05F7F540404040" 






L 


15,00C(0,12) 


V(ILBOD3G4) 




BALR 


14, 15 






L 


1,04C(0,12) 


DCB=1 




L 


3, 02C(0, 1) 






TM 


00C(3) ,X' OF' 






BALR 


5, 







388 



75 



VERB 20 



78 



VERB 21 



78 



VERB 22 



78 



79 



VERB 23 



VERB 24 



00072A 


47 


EO 


5 


010 


00072E 


58 


20 


1 


04C 


000732 


4B 


20 


1 


052 


000736 


50 


20 


1 


04C 


00073A 


58 


10 


C 


04C 


00073E 


50 


10 


D 


228 


000742 


92 


90 


D 


228 


000746 


41 


10 


D 


228 


00074A 


0A 


14 






00074C 


58 


20 


C 


04C 


000750 


58 


10 


2 


014 


000754 


96 


01 


2 


017 


000758 


IB 


44 






00075A 


43 


40 


1 


005 


00075E 


4C 


40 


1 


006 


000762 


41 


00 


4 


008 


000766 


41 


10 


1 


000 


00076A 


OA 


OA 






00076C 


58 


FO 


C 


OOC 


000770 


05 


EF 






000772 


58 


10 


C 


050 


000776 


D2 


03 


D 


060 C 018 


00077C 


D2 


02 


1 


039 D 061 


000782 


58 


10 


C 


50 


000786 


D2 


01 


1 


032 C 064 


00078C 


50 


10 


D 


228 


000790 


92 


80 


D 


228 


000794 


41 


10 


D 


228 


000798 


OA 


13 






00079A 










00079A 


58 


FO 


C 


OOC 


00079E 


05 


EF 






0007A0 


58 


FO 


c 


010 


0007A4 


05 


IF 






0007A6 


0000004E 


0007AA 


58 


FO 


c 


014 


0007AE 


05 


IF 






0007B0 


000140 




0007B3 


05] 
58 


?7F840404040 


0007BA 


FO 


c 


OOC 


0007BE 


05 


EF 






0007C0 


58 


10 


c 


050 


0007C4 


18 


21 






0007C6 


D2 


02 


2 


021 C 041 


0007CC 


58 


FO 


1 


030 


0007D0 


05 


EF 






0007D2 


50 


10 


D 


1F8 


0007D& 


c o 


80 


D 


1 t»o 


0007DA 


D2 


13 


6 


040 8 000 


0007E0 


58 


50 


C 


02C 


0007E4 


07 


F5 






0007E6 










0007E6 


58 


10 


C 


030 


0007EA 


07 


Fl 






0007EC 










0007EC 


07 


00 






0007EE 


58 


FO 


C 


OOC 


0007F2 


05 


EF 






0007F4 


58 


FO 


C 


010 


0007F8 


05 


IF 






0007FA 


0000004F 


0007FE 


58 


FO 


C 


014 


000802 


05 


IF 






000804 


000140 




000807 


05F7F940404040 



PN=03 



GN=04 



PN=04 



BC 


14,010(0,5) 






L 


2 # 04C(0,1) 






SH 


2,052(0,1) 






ST 


2, 04C(0, 1) 






L 


1,04C(0,12) 


DCB=1 




ST 


1, 228(0,13) 


SAV3 




MVI 


228(13) ,X'90' 


SAV3 




LA 


1, 228(0,13) 


SAV3 




SVC 


20 






L 


2,04C(0,12) 


DCB=1 




L 


1,014(0,2) 






01 


017<2) # X»01' 






SR 


4,4 






IC 


4,005(0,1) 






MH 


4,006(0,1) 






LA 


0,008(0, 4) 






LA 


1,000(0,1) 






SVC 


10 






L 


15,00C(0, 12) 


V(ILBODBG4) 




BALR 


14,15 






L 


1,050(0,12) 


DCB=2 




MVC 


060(4,13) ,018(12) 


WC=01 


V( ILBOERR 


MVC 


039(3,1), 061(13) 




WC=02 


L 


1,050(0,12) 


DCB=2 




MVC 


032(2, 1), 064(12) 




LIT+12 


ST 


1,228(0,13) 


SAV3 




MVI 


228(13), X'80' 


SAV3 




LA 


1,228(0,13) 


SAV3 




SVC 


19 






EQU 


* 






L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14,15 






L 


15, 010(0, 12) 


V(ILBOFLWl) 




BALR 


1,15 






DC 


X'0000004E' 






L 


15,014(0,12) 


V(ILBODSPO) 




BALR 


1.15 






DC 


X* 000140' 






DC 


X'05F7F840404040' 






L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14,15 






L 


1,050(0,12) 


DCB=2 




LR 


2,1 






MVC 


021(3, 2), 041(12) 




GN=04+1 


L 


15,030(0,1) 






BALR 


14,15 






ST 


1,1F8(0,13) 


BL =2 




L 


O 1 t»0 /A 1 1 ^ 


BL =2 




MVC 


040(20, 6), 000(8) 


DNM=l-38 2 


DNM= 1-224 


L 


5,02C(0,12) 


PN=04 




BCR 


15,5 






EQU 


* 






L 


1,030(0,12) 


PN=05 




BCR 


15,1 






EQU 


* 






BCR 


0,0 






L 


15,00C(0,12) 


V(ILBODBG4) 




BALR 


14,15 






L 


15,010(0,12) 


V(ILBOFLWl) 




BALR 


1,15 






DC 


X'0000004F' 






L 


15,014(0,12) 


V(ILBODSPO) 




BALR 


1,15 






DC 


X'000140' 






DC 


X'05F7F940404040' 
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79 



79 



VERB 25 



VERB 26 



80 



82 



VERB 28 



VERB 29 



82 



VERB 3 



83 



VERB 31 



00080E 


58 


20 


C 


044 


000812 


95 


FO 


6 


04B 


000816 


07 


72 






000818 


95 


40 


6 


04C 


00081C 


07 


72 






00081E 


92 


E9 


6 


04B 


000822 


92 


40 


6 


04C 


000826 










000826 


58 


10 


C 


068 


00082A 


50 


10 


D 


230 


00082E 


41 


20 


D 


230 


000832 


58 


FO 


C 


ooc 


000836 


05 


EF 






000838 


58 


FO 


c 


014 


00083C 


05 


IF 






00083E 


8001 






0008<*0 


10 








000841 


00000B 




000844 


OC00006C 


000848 


0000 






00084A 


00 








00084B 


000014 




00084E 


0D0001FC 


000852 


0040 






000854 


FFFF 






000856 


58 


10 


c 


028 


00085A 


07 


Fl 






00085C 










00085C 


07 


00 






00085E 


58 


FO 


c 


OOC 


000862 


05 


EF 






000864 


58 


FO 


c 


010 


000868 


05 


IF 






00086A 


00000052 


00086E 


58 


FO 


c 


014 


000872 


05 


IF 






000874 


000140 




000877 


05F8F240404040 


00087E 


58 


FO 


c 


OOC 


000882 


05 


EF 






000884 


58 


10 


c 


050 


000888 


58 


30 


1 


02C 


00088C 


91 


OF 


3 


OOC 


000890 


05 


50 






000892 


47 


EO 


5 


010 


000896 


58 


20 


1 


04C 


00089A 


4B 


20 


1 


052 


00089E 


50 


20 


1 


04C 


0008A2 


58 


10 


c 


050 


0008A6 


50 


10 


D 


228 


0008AA 


92 


90 


D 


228 


0008AE 


41 


10 


D 


228 


0008B2 


OA 


14 






0008B4 


58 


20 


C 


050 


0008B8 


58 


10 


2 


014 


0008BC 


96 


01 


2 


017 


0008C0 


IB 


44 






0008C2 


43 


40 


1 


005 


0008C6 


4C 


40 


1 


006 


0008CA 


41 


00 


4 


008 


0008CE 


41 


10 


1 


000 


0008D2 


OA 


OA 






0008D4 


58 


FO 


C 


OOC 


0008D8 


05 


EF 







GN=05 



PN=05 



L 


2,044(0,12) 


GN=05 


CLI 


04B(6),X , F0" 


DNM=2-0 


BCR 


7,2 




CLI 


04C(6),X'40" 


DNM=2-0+l 


BCR 


7,2 




MVI 


04B(6),X'E9' 


DNM=2-0 


MVI 


04C(6),X'40' 


DNM=2-0+l 


EQU 


* 




L 


1,068(0,12) 


LIT+16 


ST 


1,230(0,13) 


PRM=1 


LA 


2,230(0,13) 


PRM=1 


L 


15,00C(0,12) 


V(IL30DBG4) 


BALR 


14,15 




L 


15,014(0,12) 


V(ILBODSPO) 


BALR 


1,15 




DC 


X'8001' 




DC 


X'10' 




DC 


X'OOOOOB' 




DC 


X'0C00006C 


LIT+20 


DC 


X'0000' 




DC 


X'OO' 




DC 


X* 000014' 




DC 


X'ODOOOIFC* 


BL =3 


DC 


X'0040' 




DC 


X'FFFF" 




L 


1,028(0,12) 


PN=03 


BCR 


15,1 




EQU 


* 




BCR 


0,0 




L 


15,00C(0,12) 


V(ILBODBG4) 


BALR 


14, 15 




L 


15,010(0,12) 


V(ILBOFLWl) 


BALR 


1,15 




DC 


X' 00000052' 




L 


15,014(0, 12) 


V(ILBODSPO) 


BALR 


1.15 




DC 


X'000140' 




DC 


X'05F8F240404040' 




L 


15,00C(0,12) 


V(ILBODBG4) 


BALR 


14,15 




L 


1,050(0,12) 


DCB=2 


L 


3,02C(0,1) 




TM 


00C(3) ,X'0F' 




BALR 


5,0 




BC 


14,010(0,5) 




L 


2,04C(0,1) 




SH 


2,052(0,1) 




ST 


2,04C(0,1) 




L 


1,050(0,12) 


DCB=2 


ST 


1,228(0,13) 


SAV3 


MVI 


228(13), X' 90" 


SAV3 


LA 


1,228(0,13) 


SAV3 


SVC 


20 




L 


2,050(0,12) 


DCB=2 


L 


1,014(0,2) 




OI 


017(2), X'01' 




SR 


4,4 




IC 


4,005(0,1) 




MH 


4,006(0,1) 




LA 


0,008(0, 4) 




LA 


1,000(0,1) 




SVC 


10 




L 


15,00C(0,12) 


V(ILBODBG4) 


BALR 


14,15 





390 



0008DA 










0008DA 


58 


F0 


C 


nc 


0C08DE 


07 


FF 






0008E0 


50 


DO 


5 


008 


0008E4 


50 


50 


D 


004 


0008E8 


50 


EO 


D 


054 


0008EC 


91 


20 


D 


048 


0008F0 


47 


EO 


F 


02E 


0008F4 


58 


20 


D 


1B8 


0008F8 


91 


40 


D 


049 


0008FC 


47 


EO 


9 


000 


000900 


96 


04 


2 


000 


000904 


58 


FO 


2 


038 


000908 


41 


FO 


F 


004 


00090C 


07 


FF 






00090E 


94 


EF 


D 


048 


000912 


58 


FO 


C 


000 


000916 


05 


EF 






000918 


50 


10 


D 


1B8 


00091C 


12 


00 






00091E 


07 


89 






000920 


96 


10 


D 


048 


000924 


58 


FO 


C 


004 


000928 


05 


EF 






00092A 


05 


FO 






00092C 


91 


20 


D 


048 


000930 


47 


EO 


F 


016 


000934 


58 


00 


B 


048 


000938 


98 


2D 


B 


050 


00093C 


58 


EO 


D 


054 


000940 


07 


FE 






000942 


96 


20 


D 


048 


000946 


41 


60 





004 


00094A 


41 


10 


C 


020 


00094E 


41 


70 


C 


058 


000952 


06 


70 






000954 


05 


50 






000956 


58 


40 


1 


000 


00095A 


IE 


4B 






00095C 


50 


40 


1 


000 


000960 


87 


16 


5 


000 


we%« 


■«*!-■ 


as- 


-1F-4 


000968 


41 


70 


D 


207 


00096C 


05 


10 






00096E 


58 


00 


8 


000 


000972 


IE 


OB 






000974 


50 


00 


8 


000 


000978 


87 


86 


1 


000 


00097C 


D2 


03 


D 


224 


000982 


58 


60 


D 


1FC 


000986 


58 


70 


n 


1F4 


00098A 


58 


80 


D 


1F8 


00098E 


58 


EO 


D 


054 


000992 


07 


FE 






000000 


90 


EC 


D 


OOC 


000004 


18 


5D 






000006 


05 


FO 







GN=06 



INIT2 



INIT3 



C 054 



INIT1 



EQU 


* 




L 


15,01C(0, 12) 


v(ilbos: 


BCR 


15,15 




ST 


13,008(0, 5) 




ST 


5,004<0,13) 




ST 


14,054(0,13) 




TM 


048(13), X'20' 


SWT+0 


BC 


14,02E(0, 15) 




L 


2,1B8(0,13> 




TM 


049(13), X*40' 


SWT + 1 


BC 


14,000(0,9) 




01 


000(2), X'04' 




L 


15,038(0,2) 




LA 


15,004(0,15) 




BCR 


15,15 




NI 


048(13), X'EF' 


SWT+0 


L 


15,000(0,12) 


VIR=1 


BALR 


14, 15 




ST 


-i -i do t n 1 -} » 




LTR 


0,0 




BCR 


8,9 




01 


048(13), X'10' 


SWT+0 


L 


15,004(0,12) 


VIR=2 


BALR 


14, 15 




BALR 


15,0 




TM 


048(13), X'20« 


SWT+0 


BC 


14,016(0,15) 




L 


0,048(0,11) 




LM 


2,13,050(11) 




L 


14, 054(0, 13) 




BCR 


15,14 




01 


048(13), X'20' 


SWT+0 


LA 


6,004(0,0) 




LA 


1,020(0,12) 


PN=01 


LA 


7,058(0,12) 


LIT+0 


BCTR 


7,0 




BALR 


5,0 




L 


4,000(0,1) 




ALR 


4,11 




ST 


4,000(0,1) 




BXLE 


1,6,000(5) 




LA... 


8_,1F4(0 4 13) 


OVF=l 


LA 


7,207(0,13) 


TS^Ol-1 


BALR 


1,0 




L 


0,000(0,8) 




ALR 


0,11 




ST 


0,000(0,8) 




BXLE 


8,6,000(1) 




MVC 


224(4,13) ,054(12) 


VN=01 


L 


6,1FC(0,13) 


BL =3 


L 


7,1F4(0,13) 


BL =1 


L 


8,1F8(0,13) 


BL =2 


L 


14,054(0,13) 




BCR 


15,14 




STM 


14,12, 00C(13) 




LR 


5,13 




BALR 


15,0 





VNI=1 
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000008 

oooooc 
000014 

000018 
00001A 
00001E 
000020 
000024 
000026 
00002A 
00002C 
000030 
000034 
000038 
00003C 
000040 
000044 
000048 
000084 



45 80 F 010 

E3C5E2E3D9E4D540 

C1D5E2F4 

07 00 

98 9F F 024 

07 FF 

96 02 1 034 

07 FE 

41 FO 001 

07 FE 

0QQ00924 

00000000 

00000000 

00000498 

00000248 

00000510 

O0OO08E0 

00000000 



5 RT 8 010(0.155 

DC X'E3C5E2E3D9E4D540' 

DC X'C1D5E2F4' 

BCR 0,0 

LM 9,15,024(15* 

BCR 15, 15 

OI 034(1), X'02' 

BCR 15, 14 

IA 15,001(0,0) 

BCR 15, 14 

ADCON L4(INIT3) 

ADCON L4(INIT1) 

ADCON L4(INIT1) 

ADCON L4(PGT) 

ADCON L4(TGT) 

ADCON L4( START) 

ADCON L4(INIT2) 

DS 15F 

DC X' 00000000' 



♦STATISTICS* SOURCE RECORDS = 84 DATA DIVISION STATEMENTS = 2 5 

♦OPTIONS IN EFFECT* SIZE = 81920 BUF = 2768 LINECNT = 57 SPACEl, 

♦OPTIONS IN EFFECT* DMAP, PMAP, NOCLIST, NOSUPMAP, NOXREF, SXREF, 

♦OPTIONS IN EFFECT ♦ NOTERM, NONUM, NOBATCH, NONAME, COMPILE=01, STATE, 
♦OPTIONS IN EFFECT* NOOPT, NOSYMDMP 



PROCEDURE DIVISION STATEMENTS = 
FLAGW, SEQ, SOURCE 

LOAD, NODECK, QUOTE, NOTRUNC, FLOW= 
NORESIDENT, NODYNAM, NOLIB, NOSYNTAX 



CROSS-REFERENCE DICTIONARY 



DATA NAMES 



DEFN 



REFERENCE 



A 

ALPHA 

ALPHABET 

B 

DEPEND 

DEPENDENTS 

FIELD-A 

FIELD-A 

FILE-1 

FILE- 2 

KOUNT 

LOCATION 

NAME-FIELD 

NO- OF- DEPENDENTS 

NOMBER 

RECORD- NO 

RECORD- 1 

RECORD- 2 

RECORDA ' 

WORK- RECORD 



000055 
000041 
000040 
000056 
000044 
000042 
000027 
000035 
000016 
000017 
000037 
000050 
000046 
000052 
000038 
000048 
000026 
000034 
000054 
000045 



000065 



000067 
000068 



000061 000070 
000075 000078 
000061 000065 



000065 

000068 000079 

000061 000065 

000069 

000070 

000078 



000070 000078 000080 



000075 
000082 
000068 000072 



000069 



392 



PROCEDURE NAMES DEFN REFERENCE 



BP.GIN 000058 

3TEP-1 000061 

STEP-2 000065 000072 

STEP-3 000070 000072 

STEP-4 000072 

STEP-5 000075 

STEP-6 000078 000080 

STEP-7 000079 

STEP-8 000082 000078 



IKF1100I-W 2 SEQUENCE ERRORS IN SOURCE PROGRAM. 
55 IKF2190I-W PICTURE CLAUSE IS SIGNED, VALUE CLAUSE UNSIGNED. ASSUMED POSITIVE. 



61 
65 
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APPENDIX B: COBOL LIBRARY SUBROUTINES 



COBOL library subroutines perform 
operations that require such extensive 
coding that it would be inefficient to 
place the coding in the object module each 
time it is needed. 



that are being used by another program in 
the region/partition. It also deletes any 
subprogram in the CANCEL literal or CANCEL 
identifier statement. 



COBOL library subroutines are stored in 
the COBOL library (SYSl.COBLIB) . The 
required subroutines are inserted in load 
modules by the linkage editor. 

There are several major categories of 
COBOL library subroutines, namely: 
subprogram linkage, object-time program 
operations (i.e., data conversions, 
arithmetic operations, test conditions, 
data manipulation, data management, and 
special features), and object-time 
debugging. The categories are described in 
this order. 

Table 35 later in this chapter includes 
a list of COBOL library subroutines, their 
storage requirements, and the associated 
calling information. 

In addition, Q routines, which are not 
classified as COBOL library subroutines, 
are used to calculate the length of 
variable-length fields and the location of 
variably located fields resulting from an 
OCCURS clause with a DEPENDING ON option. 



STOP RUN Version 4 Subroutine (ILBOSRVO) 



The ILBOSRV subroutine is called by all 
programs compiled by the Version 4 
compiler. This routine returns control to 
the system, if the calling program is the 
main program, or to the caller, if it is 
not. 



STOP RUN Subroutine (ILBOSTPO) 



The ILBOSTP subroutine acts as a 
non-reenterable interface between a program 

compiled by the I BM_. Full American National 

Standard COBOL Version 3 Compiler, or a 
non-COBOL program and the Version 4 
subroutine library. It may be entered from 
COBOL programs or subprograms. 



SUBROUTINES FOR SUBPROGRAM LINKAGE 



OBJECT-TIME PROGRAM OPERATIONS 



The subroutines that control the loading 
of library subroutines or subprograms and 
the exiting from programs or subprograms 
are described here. 



ENTER Subroutine (ILBONTRO) 



The ILBONTRO subroutine is used (1) when 
the RESIDENT option is an effect, to load 
one copy of each subroutine called by the 
main program or any of its subprograms into 
any region/partition; and (2) when the 
DYNAM option is in effect, to call any 
subprogram specified in a CALL literal or 
CALL identifier statement, first loading it 
if it has not already been loaded into that 
region/partition. 

When a program finishes execution, this 
routine deletes all the subroutines called 
by the program except those subroutines 



COBOL LIBRARY CONVERSION SUBROUTINES 



Eight numeric data formats are permitted 
in COBOL — five external (for input and 
output) and three internal (for internal 
processing) . 

The five external formats are these: 

(1) external or zoned decimal, (2) external 
floating-point, (3) sterling display _. 

(4) numeric edited, and (5) sterling 
report. The three internal formats are 
these: (1) internal or packed decimal, 

(2) binary, and (3) internal 
floating-point. 

The conversions from internal decimal to 
external decimal, from external decimal to 
internal decimal, and from internal decimal 
to numeric edited are done in-line. The 
other conversions are performed by the 
COBOL library subroutines shown in Table 
33, and by the separate sign subroutine. 
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Separate Sign Subr outin e (ILB OSSNO) 



The ILBOSSNO subroutine converts 
separately signed data-names to internal 
decimal format and then checks for a valid 



sign. If the sign is valid, this 
subroutine generates the corresponding 
overpunch in the receiving field. If not, 
it causes an object time message to be 
issued and the job to be terminated. 



Table 33. Functions of COBOL Library Conversion Subroutine (Part 1 of 2) 



r - 


Subroutine Name 
and 
Entry Points 


1 
L 




Conversion 




i 


r 

± 


From 




T 


TO 


1 


ILB0EFL2 




T 


External Floating- 


-point 


T 


Internal Decimal 




ILBOEFLl 






External Floating- 


-point 




Binary 


1 


ILBOEFLO 




_L 


External Floating- 


-point 


± 


Internal Floating-point 




ILBOBIDO 1 




T 


Binary 




T 


Internal Decimal 




ILBOBID1 1 














I 


ILBOBID2 :L 




L_ 






J._ 




I 


ILBOBIEO* 




— r 


Binary 




T 


External Decimal 




ILBOBIEl*- 














1 


ILBOBIE21 




4. 






_L 




1 


ILBOBIIO 2 




T 


Binary 




T 


Internal Floating-point 


1 


ILBOBIIl 2 




-X - 






1 




1 


ILBOTEFO 2 




T 


Binary 




T 


External Floating-point 




ILBOTEF1 2 
















ILBOTEF2 






Internal Decimal 






External Floating-point 


1 


IFBOTEF3 




— 1- - 


Internal Floating- 


-point 


4. 


External Floating-point 




ILBOIBDO 




r 


Internal Decimal 




T 


Binary 


I 


ILBOIDB1 




-X - 


External Decimal 




X- 


Binary 




ILBODCI1 




T 


Internal Decimal 




T 


Internal Floating-point 


i 


ILBODCIO 




-X . 


External Decimal 




X 


Internal Floating-point 


I 


ILBOIFDO 




T 


Internal Floating- 


-point 


T 


Internal Decimal 


1 


ILBOIFD1 




J. . 


Internal Floating- 


■point 


J. 


External Decimal 


1 

1 i 

1 s 
1 3 


The entry points used depend on whether the double-precision number is in registers 

and 1, or 2 and 3, or 4 and 5, respectively. 

The entry points are for single-precision binary and double-precision binary, 

respectively. 

This entry point is used for calls from other COBOL library subroutines. 
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Table 33. Functions of COBOL Library Conversion Subroutines (Part 2 of 2) 

r t 



| Conversion | 


and | | | 

Entry Points | From j To j 

- - 4- 4- J 


T T 1 
ILB0IFB1 | Internal Floating-point | Binary integer and a power | 

j | of 10 exponent j 

ILB0IFB2 3 | | | 

ILBOIFBO 3 j Internal Floating-point j Binary j 

+ + 4 

ILBOIDR0 | Internal Decimal | Sterling Report | 
4 4 j 

ILBOIDT0 | Internal Decimal | Sterling Non-Report j 
_ _ 4. 4- 4 


T T 1 

ILBOSTI0 | Sterling Non-Report | Internal Decimal | 
_ J. - __ x - - 4 


T T 1 

ILBOCVB0 | External decimal | Binary | 

- 4- 4- 4 


T T 1 

ILBOCVB1 | External decimal | Binary | 
j. ± __ _ J 


^-The entry points used depend on whether the double-precision number is in registers j 
and 1, or 2 and 3, or 4 and 5, respectively. j 

2 The entry points are for single-precision binary and double-precision binary, j 
respectively. j 

3 This entry point is used for calls from other COBOL library subroutines. j 



Table 34. Function of COBOL Library Arithmetic Subroutines 

■T 



j Subroutine Name 



Function 



ILBOXMU0 



y 

IILBOXDI0 



Internal Decimal Multiplication t30 digits * 30 digits = b0 digits) 



Internal Decimal Division (60 digits/30 digits = 60 digits/ 



h- 

i; 
h 
n 
I- 

| ^The ILBOGPW0 entry point is used if the exponent has a picture specifying an integer. 
| The ILBOFBW0 entry point is used in all other cases. 

L 



ILBOXPR0 



Exponentiation of an Internal Decimal Base by a Binary Exponent 



ILBOFPW0 



Floating-point Exponentiation 



ILBOGPWO* 



Floating-point Exponentiation 



Appendix B: COBOL Library Subroutines 397 



COBOL LIBRARY ARITHMETIC SUBROUTINES 



Most arithmetic operations are performed 
in-line. However, involved calculations, 
such as exponentiation, and calculations 
with very large numbers, such as decimal 
iUuj.tipxic3v-iori Oj. two ju'uiyit nurnu>ers, are 
performed by COBOL library subroutines. 
These subroutine names and their functions 
are given in Table 34. 



COBOL LIBRARY SUBROUTINES FOR TESTING 
CONDITIONS AT OBJECT TIME 



Several subroutines are used to test 
conditions that determine the path of 
control the object program selects. Such 
subroutines are described below. 



Class Test Subroutine (ILBOCLSO) 



The ILBOCLSO subroutine is used to 
perform class tests for variable-length 
items and those fixed-length items over 25b 
bytes long, to determine whether a field is 
alphanumeric. 

N ote : The following tables are placed in 
the library for use by the in-line coding 
generated and the subroutines called for by 
both class test and TRANSFORM: 

ILBOATBO — alphabetic class test 
ILBOETBO — external decimal class 

test 
ILBOITBO — internal decimal class 

test 
ILBOTRNO — transformation 
ILBOUTBO — unsigned internal decimal 

class test 
ILBOWTBO — unsigned external decimal 

class test 



figurative constant must always be the 
second operand. If it is first in the 
source program, the operands are reversed 
and the condition code to be passed on is 
inverted before this subroutine is called. 



COBOL LIBRARY DATA MANIPULATION SUBROUTINES 



Subroutines are used to manipulate data 
in main storage in response to the MOVE, 
TRANSFORM, STRING, and UNSTRING statements. 
(Data manipulation in response to the 
EXAMINE statement is performed in-line by 
the ooject program. ) 



MOVE Suoroutine (ILBOVMOO and ILBOVMDD 



two 



The MOVE suoroutine is used when one or 
both operands is variaole in length. They 
may exceed 256 bytes. The MOVE subroutine 
is also used for READ and WRITE statements 
processed in conjunction with the S^ME 
RECORD AREA clause. The subroutine has 
entry points, depending on the type of 
move: ILBOVMOO (left- justified) and 
ILB0VM01 (right-justified). 



MOVE Su broutin e for System /370 (ILBOSMVO) 



This special MOVE subroutine is used 
when the length of the receiving field is 
either greater than 512 bytes or variaole. 
The subroutine transfers characters to a 
right- justified receiving field. 



MOV E to Alphanumeric-Edite d Field 
Subroutine (ILBOANEO) 



COMPARE Subroutine (ILBOVCOO) 



The ILBOVCOO subroutine compares two 
operands, one or both of which are of 
variable lengths. They may exceed 256 
bytes. 



Compa re with Fi gurati ve Const ant Subroutine 
(ILBOIVLO) 



The ILBOIVLO subroutine compares the 
identifier to a figurative constant. The 



The ILBOANEO subroutine moves a 
data-name, literal, or figurative constant 
into a right- or left- justified 
alphanumeric edited field. 



MOVE to Numeric-Edited Field Subroutine 



(ILBONEDO) 



The ILBONEDO subroutine is called by the 
UNSTRING subroutine to move characters from 
a packed decimal field into a 
numeric-edited receiving field. 
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TRANSFORM Subroutine (ILBOVTRO) 



5. External floating-point 



The ILBOVTRO subroutine translates 
variable-length items. 



STRING Subroutine (ILBOSTGO) 



The ILBOSTGO routine combines the 
partial or complete contents of two or more 
subfield(s) into a single field. This 
routine transfers characters from the 
sending item(s) to the receiving item in 
the same way that moves from alphanumeric 
item(s) to alphanumeric item(s) are 
effected. 



UNSTRING Subroutine (ILBOUSTO) 



The ILBOUSTO routine separates 
continuous data in a sending field, placing 
it in multiple receiving fields. 



Internal floating-point numbers must be 
converted to external floating-point 
numbers before the subroutine is called. 



Note: 



If the contents of a data-name are 



such that when converted they will exceed 
18 decimal digits, the ILBODSPO subroutine 
cannot process them and the results are 
unpredictable. 



DISPLAY Subroutine (ILBODSSO) 



The ILBODSSO subroutine prints or types 
data of a certain kind on SYSPRINT or at 
the console. This subroutine is used 
instead of ILBODSPO when there are no 
requests by the program for TRACE or 
EXHIBIT, and no variable-length or 
floating-point items; when there are no 
requests for display upon SYSPUNCH; and 
when neither the RESIDENT nor the DYNAM 
option is in effect. 



COBOL LIBRARY DATA MANAGEMENT SUBROUTINES 



ACCE PT_ Subroutine ( ILBO ACPO) 



COBOL library subroutines are called to 
process the following verbs: DISPLAY, 
TRACE, EXHIBIT, ACCEPT, START (when generic 
key is specified), READ (BSAM), WRITE 
(BSAM), CLOSE (BSAM), OPEN (BSAM), RECEIVE 
(TCAM), and SEND (TCAM) ; library 
subroutines are also called for I/O errors, 
printer spacing, and printer overflow. 



DISPLAY, TRACE, and EXHIBIT Subroutine 
(ILBODSPO) 



The ILBODSPO subroutine is used to 
print, punch, or type data, usually in 
limited amounts, on an output unit. TRACE 
and EXHIBIT are kinds of DISPLAY. 

The acceptable forms of data for this 
subroutine are: 

1. Display 

2. External decimal 

3. Internal decimal (converted by the 
subroutine to external decimal) 

4. Binary (converted by the subroutine to 
external decimal) 



The ILBOACPO subroutine is called to 
read from SYSIN or from the operator's 
console at execution time. For SYSIN, a 
logical record size of 80 is assumed. If 
the size of the data item being accepted is 
less than 80 characters, the data must 
appear as the first set of characters 
within the input record. If the size of 
the data item is greater than 8 
characters, as many records as necessary 
are read until the storage area allocated 
to the data item is filled. If the data 
item is greater than 80 characters, but is 
not an exact multiple of 80, the remainder 
of the last logical record is not 
accessible. For the console, a maximum of 
114 characters are accepted and either 114 
characters or the length of the item, 
whichever is smaller, is moved to the 
operand named in the ACCEPT statement. 



Generic Key S TA RT Subr o utine (ILBO STR 0) 



The ILBOSTR0 subroutine is called when a 
USING KEY clause is coded with the START 
verb for ISAM files. The subroutine 
formats the search argument so that data 
management can get control to search for 
the generic key. 
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Checkpoint Subroutine (ILBOCKPO) 



BSAM READ Subroutine (ILBOSPNO) 



The ILBOCKPO subroutine generates a 
checkpoint record, continuing the status of 
a program when a checkpoint is taken. This 
record is written on a checkpoint data set. 



The BSAM read routine reads segments of 
a logical record and assembles them into a 
complete logical record. The routine is 
called by a compiler-generated READ code 
for a spanned record direct BSAM file. 



Error Intercept Subroutine (ILBOERRO ) 



RECEIVE Subroutine (ILBORECO) 



The ILBOERRO subroutine is used to test 
for various error conditions, and passes 
control to the interpretive-statement 
specified in the INVALID KEY option phrase 
or to the USE FOR ERROR declarative section 
depending on the type of error and error 
handling options specified. The entry 
points used for error processing by 
ILBOERRO are: 

ILBOERR1 Standard Sequential Files 

ILBOERR2 Direct and Relative Files 

Accessed Sequentially 
ILBOERR3 Indexed Files Accessed 

Sequentially 
ILBOEER4 Direct and Relative Files 

Accessed Randomly 
ILBOERR5 Indexed Files Accessed 

Randomly 



The ILBORECO subroutine transfers a 
message, a message segment, or part of a 
message or message segment from the message 
control program to the COBOL application 
program. This routine always updates the 
input communication description (CD) entry 
as well as processes the IF MESSAGE 
clause(s), if any. 



RECEIVE Initialization Subroutine 
(ILBORNTO) 



The ILBORNTO subroutine builds the 
control block that communicates with the 
input queue associated with the cdname 
specified in the RECEIVE statement. 



Printer Overflow Subroutine (ILBOPTVO) 



Queue A nalyzer Object-Time Subrout ine 
(ILBOSQAO) 



The ILBOPTVO subroutine is used to 
control printer overflow testing and page 
ejection. 



Print er Spacing S ub routine (IL BOSPAO) 

The ILBOSPAO subroutine is used to 
control printer spacing. 



The ILBOSQAO subroutine is called by the 
ILBORECO routine if the COBTPQD data set is 
present. This routine searches the COBTPQD 
data set for a member that corresponds to 
the name in the SYMBOLIC QUEUE field 
(defined in the COBOL source statements). 
If a match is found, the analyzer reads the 
member into main storage, using it to 
validate the SYMBOLIC SUB- QUEUE name(s) in 
the input CD of the COBOL source program. 
The analyzer also identifies the first 
valid DD name for the queue structure and 
gives this name to the ILBORECO routine. 



BSAM WRITE/CLOSE and BDAM OPE N Subroutine 
(ILBOSAMO) 



Queue S tructure Description Subrout ine 
(ILBOQSUO) 



The ILBOSAMO routine processes 
input/output statements for direct or 
relative files accessed sequentially. It 
also handles OPEN statements and CLOSE 
statements with the REEL option for 
directly organized output files accessed 
randomly. 



The ILBOQSUO subroutine creates a 
partitioned data set with one member for 
each queue structure defined in the 
COBOL-like source statements. This routine 
also generates a printed listing of the 
structure element, as well as of error 
messages, if any. 
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SEND Subroutine (ILBOSNDO) 



Segme ntation S ubroutine (ILBQSGMO) 



The ILBOSNDO subroutine transfers a 
message, a message segment, or part of a 
message or message segment from the COBOL 
application program to the message control 
program. This routine always updates the 
output CD entry. 



The ILBOSGMO subroutine is used to load 
segments of a program that are not in core 
storage and to pass control from one 
segment to the other. 



GO TO DEPENDING ON Subroutine (ILBOGDOO) 



SEND Initialization Subroutine (ILBOSNTO) 



The ILBOSNTO subroutine (ILBOSNTO) 
subroutine builds the control block that 
communicates with the output queue 
associated with the cdname specified in the 
SEND statement. 



The ILBOGDOO subroutine uses the value 
of a particular data-name as an index into 
a list of constants for each PN specified 
and then transfers control to the proper 
PN. If the value of the data-name is 
greater than the number of PN* s specified, 
control returns to the next instruction 
after the calling sequence. 



Date-and-Time Subroutine (ILBODTEO) 



COBOL LIBRARY SUBROUTINES FOR SPECIAL 
FEATURES 



Subroutines are used "for three of the 
special features of COBOL: 

• Sort feature 

• Table handling feature (SEARCH 
statement) 

• Segmentation feature (GO TO statement) 

Also, a subroutine is called in response to 
the use of the following special registers: 
CURRENT-DATE, DATE, DAY, TIME, and 
TIME-OF-DAY. 



This group of subroutines performs five 
functions in response to the use of the 
special registers CURRENT-DATE, DATE, DAY, 
TIME, and TIME-OF-DAY. The list below 
indicates the function of __each of the entry 
..___,____.. -—£- "the - format ""of "each result in 
the receiving field of the specified MOVE 
or ACCEPT statement. 

ILBODTEO — day/month/year 

ILBODTE1 -- hour minute second 

ILBODTE2 — year month day 

ILBODTE3 — year day 

ILBODTE4 — hour minute second 

hundredth of a second 



Sort Feature Subroutine (ILBOSRTO) 



The ILBOSRTO subroutine acts as an 
interface between the COBOL calling program 
and the Sort/Merge program via the entry 
point name SORT. 



SEARCH Subroutine (ILBOSCHO) 



The ILBOSCHO subroutine performs a 
binary search on a specified level of a 
table. It is used for the SEARCH ALL 
statement. 



OBJECT-TIME DEBUGGING 



Three options are available for 
object- time debugging: the statement 
number option (STATE), the flow trace 
option (FLOW), and the symbolic debugging 
option (SYMDMP). The subroutines for the 
first two options provide debugging 
information at aonormal termination of a 
program; the subroutines for the third 
option provide debugging information either 
at abnormal termination or dynamically 
during the execution of a program. All of 
these subroutines are under the control of 
and are supervised by the debug control 
subroutine ILBODBGO. The debug control 
subroutine is described first, followed by 
the subroutines that are called in response 
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to the specification of the STATE, FLOW, 
and SYMDMP options. 



The ILBODBGO subroutine is called once 
at entry point ILBODBGO for each COBOL 
program for which any of the debugging 
options have been specified. This 
subroutine handles linkage and input/output 
for the STATE, FLOW, and SYMDMP options. 
It also produces the program name, the 
condition code, and the last PSW message at 
the time of the abnormal termination. 



Flow Trace Subroutine (ILBOFLWO) 



The ILBOFLWO subroutine produces a 
formatted trace of the last "n" of COBOL 
procedures executed prior to an ABEND. It 
initializes, builds, and writes out the 
flow trace table. 



Statement Number Subroutine (ILBOSTNO) 



The ILBOSTNO subroutine processes the 
STATE option and determines both the card 
number and the verb number for the last 
statement executed before the ABEND, and 
then generates a message containing this 
information. 



Symbo lic Dump Subr outin e (ILB OD10 and 
ILBOD20) 



The ILBOD10 subroutine is called when 
the SYMDMP option is in effect; this 
routine calls other modules as necessary 
for SYMDMP initialization. The ILBOD20 
subroutine services SYMDMP output requests 
from DBGO. SYMDMP generates the following 
information as output on the SYSDBOUT data 
set: a copy of all SYMDMP control 
statements; diagnostic messages; dynamic 
dumps of user-selected data areas at 
strategic points during program execution; 
an abnormal termination statement number 
message; and the complete abnormal 
termination dump. In addition, 
modifications are made to the COBOL program 
in main storage if dynamic dumping is 
requested for the program. 



Note: When SYMDMP services are requested 
for a job step, the sequence of events is, 
in general, as follows: (1) initialization 
— for the first COBOL program in a job 
step, then for all other COBOL programs in 
that job step, and finally for independent 

X~)fCiCIfFi m c !f i 3rr! c>r1+ ' c " I O \ nrnnocqinn — — f i ruf 

fi.UVji.Ulll OV.v)u>^iii.U| \ *- r [•I. wv^v,^^ -*-"r> *-~.m — 

for dynamic dump requests, and then for 
abnormal termination dumps. 



SYMDMP ErrorMessageSubroutine (ILBODBEO ) 



"ERRTN" of ILB0DBG1 entry point 

The ILBODBEO subroutine is called by the 
PRINT routine of the debug control 
subroutine to format the appropriate error 
message in the SYSDBOUT output buffer. 

For additional information on the FLOW, 
STATE, and SYMDMP options and their 
relationship to other COBOL options, see 
the chapter entitled "Symbolic Debugging 
Features" and the section "Options for the 
Compiler" in the chapter entitled "Job 
Control Procedures. " 

Table 35 includes a list of COBOL 
library subroutines, their storage 
requirements, and the associated calling 
information. The subroutines are arranged 
alphabetically by the characters following 
' ILBO' . The list includes subroutines that 
are called directly by the object program 
— primary subroutines -- and tne 
subroutines they call — second ary 
subroutines. Some subroutines (for 
example, ILBOANE) function as both primary 
and secondary subroutines. 

The superscripts that accompany several 
of the entries refer to footnotes at the 
end of the table. Footnotes that appear 
with the names of subroutines indicate 
routines that are conditionally obtained, 
that are secondary subroutines only, or 
that may never reside in the MVT link pack 
area (LPA) or the MFT resident reusable 
routine area (RRR). The footnotes that 
appear with some of the numeric values 
indicate whether the information represents 
a maximum value, a minimum value, or an 
estimated value. In all cases, the numeric 
values represent decimal bytes rounded off 
to the nearest 50. 

For descriptions of the primary 
subroutines and of the major secondary 
subroutines, see the sections of this 
appendix entitled "Subroutines for 
Subprogram Linkage," "Object-Time Program 
Operations, " and "Object-Time Debugging. " 
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Table 35. Calling and Storage Information for COBOL Library Subroutines (Part 1 of 5) 









| Primary 


Calling 


Size 


Dynamic 


| Secondary |Size 


| Dynamic 


Total 


j Subroutine 


Information 




Work Area | Subroutines | 


j Work Area 


Amount 
















j ILBOACP 


Called by compiled 


500 


100 


| None | 




600 


j (ACCEPT) 


code 










3002 
23003 


| ILB0ANE 


Called by compiled 


350 





j None j 




350 


| (MOVE alphanumeric- 


code and by 












j edited field) 


ILBOUST 












| ILB0ANF 


Called by compiled 


150 





j None j 




150 


j (MOVE figurative 


code 












j constant) 














| ILBOATB 


Used for ILBOCLS 


300 





j None j 




300 


j (Alphabetic table 














| for class test) 














| ILBOBID 


Called by compiled 


150 





j None j 




150 


| (Binary to internal 


code 












j decimal ) 














| ILBOBIE 


Called by compiled 


150 





j None j 




150 


j (Binary to external 


code 












| decimal) 














| ILBOBII 


Called by compiled 


500 





j None | 




500 


| (Binary to internal 


code and by 












j floating-point) 


ILB0DCI, ILBOEFL 












I ILBOCKP 


Called by compiled 


100 





j None j 




100 


j (Checkpoint) 


code 












|__ 









1- I 






jlLBOCLS 


Called by compiled 


150 









150 


j (Class test) 


code 












|ILBOCOM* 9 


Link-edited or loaded 


150 





j None j 




150 


j (Subroutine 


by compiled code 












j communications) 


and by ILBOSRV; 
used by most COBOL 
library subroutines 












| ILBOCVB 


Called by compiled 


1050 


300 s 


j None j 




1350 


| (Decimal to 


code and by 












j binary/binary 


ILBOUST and ILB0STG 












j to decimal) 














| ILBODBG 


Called by compiled 


2725, 


950 7 


| ILB0DBG1 | 






j (Debug control) 


code if FLOW, 
STATE, or SYMDMP 
is specified 






| ILBODBG 2 j 

| ILBODBG 3 j 
j ILBODBG4 j 
| ILB0DBG5 | 
| ILB0DBG7 | 
jlLBODBE 7 8 |1200 
jlLBOSTN 7 J1109 
jlLBOFLW 7 J1600 
jlLBODOl 7 8 | 750 


1 o 

j 110 
|600 3 
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Table 35. Calling and Storage Information for COBOL Library Subroutines (Part 2 of 5) 



| Primary 
j Subroutine 

L J 


Calling | 
Information | Size 

L ± J 


Dynamic 
Work Area 

L | 


Secondary 
Subroutines 

L j 


Size 

L J 


Dynamic 
Work A.rea 

L J 


Total 
Amount 

L 


r — 1 

JILBOD010 


Called when SYMDMP | 
is in effect | 




ILBODIO 

ILBOD11 7 
ILB0D12 7 
ILB0D13 7 
ILB0D14 7 
ILBOD20 7 
ILB0D21 7 
ILBOD22 7 
ILB0D23 7 
ILBOD24 7 
ILB0D25 7 


8 
8 
8 
8 
8 
8 
8 
8 
8 
8 


2550 1 

750 
1750 1 
1550 
1500 

950 
1500 
2500 
3800 
4050* 
1200 1 - 


3100 






25/ODO 








| ILBODCI 

| (Decimal to internal 

| floating-point) 


Called 
code 


by 


compiled j 




ILBOIDB 




150 





822 


| ILBODSP 

| (DISPLAY, TRACE, 

| EXHIBIT) 


Called 
code 


by 


compiled |1938 


104 


None 








2100 


| ILBODSS 4 * 
| (DISPLAY) 


Called 


by 


compiled j 350 1 





None 








350 1 


| ILBODTE 

j (Date, day, and 

| time) 


Called 
code 


by 


compiled j 500 





None 








350 


| ILBOEFL 
| (Conversion 
j from external 
| floating-point) 


Called 
code 


by 


compiled j 600 





ILBOIOB 
ILBOBII 




150 
450 






1200 


| ILBOERR 

j (Error intercept) 


Called 


by 


the system j 500 





None 








500 


| ILBOETB 

j (External decimal 
j table for class 
j test) 


Used by ILBOCLS | 300 





None 








300 


| ILBOFLW 

j (Flow trace option) 


Called 
code 


by compiled J1600 
and by ILBODBGJ 


600 3 


None 








2300 3 


| ILBOFPW 

j (Floating-point 

j exponentiation) 


Called 
code 


by 


compiled j 800 





None 








800 


| ILBOGDO 

|(GO TO DEPENDING ON) 


Called 
code 


by 


compiled j 100 





None 








100 


| ILBOGPW 

j (Floating-point 

j exponentiation to a 

j binary exponent) 


Called 
code 


by 


compiled j 100 





None 








100 


| ILBOIDB 

| (Decimal to binary) 


Called 
code 


by 
or 


compiled j 150 
by ILBODCI | 





None 








150 



L X J. -L J- -L J- -L J 
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Table 35. Calling and Storage Information for COBOL Library Subroutines (Part 3 of 5) 



| Primary 
| Subroutine 


Calling 
Information 

i j 


Size 

L 


| Dynamic | Secondary | 

j Work Area j Subroutines! Size 

-J. -L _L 


Dynamic | Total 
Work Area j Amount 

L J. 


| ILBOIDR 

| (Internal decimal 

j to sterling report) 


Called 
code 


by compiled 


1700 


1 o 


j None j 


| 1700 


1 ILBOIDT 

| (Internal decimal to 

j sterling non- 

| report) 


Called 
code 


by compiled 


600 


1 o 


j None j 


| 600 


| ILBOIFB 

| (Internal 

j floating-point to 

j decimal or binary) 


Called by compiled 
code or by ILBOIFD 
or ILBOTEF 


300 


1 o 


j None j 


| 300 


1 ILBOIFD 

| (Internal floating 
j to decimal or 
j binary) 


Called 
code 


by compiled 


200 


1 o 


| ILBOIFB | 300 


| 


| ILBOITB 

j ( Internal decimal 
| table for class 
j test) 


Called 
code 


by compiled 


300 


1 o 


j None j 


i | 300 


j ILBOIVL 

j (Comparison with 

j figurative 

| constant) 


Called 
code 


by compiled 


100 


i o 

\ 


j None j 


| 100 


| ILBOPTV 

ftPrintex- overflow)- — 


Called 
— cade 


by compiled 


150 


1 o 


| None j 
"t "I" 


1 150 


IILBOQSU" *-° 

j (Queue structure 

| utility program) 


Called 


by JCL 


6500 


|4000 


j None j 


| 10, 500 


| ILBOREC 
| (RECEIVE) 

| ILBOSAM 

| (BSAM WRITE and 

| CLOSE/BDAM OPEN) 


Called 
code 

Called 
code 


by compiled 
by compiled 


2400 
1104 


1 o 
1 o 


IILBORNT 7 j 900 
IILBOSOA*- |2000 
j None j 


255/queue j 

blocks j 
200/buffer j 

units J3800 2 
PDS member j 
SIZE | 

| 1104 


| ILBOSCH 
j (SEARCH) 


Called 
code 


by compiled 


700 


1 o 


j None j 


1 700 


| ILBOSGM 

j (Segmentation) 


Called 
code 


by compiled 


400 


1 o 


|ILBODBG I2000 1 


600 2 I3000 1 2 



L X -L J. -L i -L X J 
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Table 35. Calling and Storage Information for COBOL Library Subroutines (Part 4 of 5) 



r i 
| Primary 
| Subroutine 

L _ _ J 


r - i 

Calling 
Information 

L J 


r i 
Size 

L J 


r i 

Dynamic 
Work Area 

L J 


r - i 

Secondary 
Subroutines 

I - _ _ j 


r i 
Size 

L J 


r t 

Dynamic | lotal 
Work Area j Amount 

1- - 4- 


r 1 

j ILBOSMV 

j (MOVE to right— 

j justified field for 

| System/370) 


r 

Called 
code 


by 


compiled 


r 1 
50 


r i 



r 1 
None 


r 1 


r t 

1 50 


\ ILBOSND 
j (SEND) 

IILBOSPA 

j (Printer spacing) 


Called 
code 

Called 
code 


by 
by 


compiled 
compiled 


1450 






ILBOSNT 1 
None 


600 


255/queue j 

blocks j 

200/buffer| 

200/bufferj 

j 1000 


I ILBOSRT 
| (Sort) 


Called 
code 


by 


compiled 


900 


200 


None 




| 1100 


| ILBOSRV 

j ( STOP RUN 

| for Version 4) 


Called by a program 
compiled by the 
Version 4 compiler 


300 





None 




| 300 


|ILBOSSN 

j (Separately 

| signed numeric) 


Called 
code 


by 


compiled 


200 1 - 





ILBOSRV 
ILBODBG 


300 
2000 3 - 


1 
600 2 | 3100 1 2 


| ILBOSTG 
I (STRING) 


Called 
code 


by 


compiled 


600 





ILBOCVB 


1050 


300 | 1950 


| ILBOSTI 

j (Sterling non-report 

j to internal decimal] 


Called 
code 


by 


compiled 


600 





None 




| 600 


| ILBOSTN 

| (Statement number 

j option) 








1100 


110 


ILBODBG 


2000* 


600 2 | 3950 1 2 


| ILB0STP 
| (STOP RUN) 


Called by 
program 


a non-COBOL 


lOO 1 - 





ILBOSRV 


300 


| 400 1 - 


| ILBOSTR 

I ( START with 

| generic key) 


Called 
code 


by 


compiled 


100 





None 




| 100 


| ILBOTEF 

| (Conversion to 

j external 

j floating-point) 


Called 
code 


by 
or 


compiled 
by ILBOD23 


700 





ILBOBIE 


150 


1 


| ILB0TRN 

| (TRANSFORM table) 


Used by ILB0VTR 


300 





None 




| 300 


| ILB0UST 
j (UNSTRING) 


Called 
code 


by 


compiled 


2000 


250 s 


ILBONED 7 8 

ILBOANE 7 8 
ILBOCVB 7 


1400 

350 
1050 


1 

| 5050 3 



L X X J. X X X X J 
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Table 35. Calling and Storage Information for COBOL Library Subroutines (Part 5 of d) 



_ T T T" 

Dynamic | Secondary 
Size I Work Area Subroutines I Size 



T T 

Dynamic 
Work Area 



Primary 
Subroutine 



Calling 
Information 



Total 
Amount 



ILBOVTB 

(Unsigned internal 
decimal table 
for class test) 

ILBOVCO 

(Variable-length 
comparison) 



(Variable-length 
name) 



Called by compiled 
code 



Called by compiled 
code 



»1 1 Q/3 Kit r* 

code 



300 



550 







ILBOVTR 
(TRANSFORM) 

ILBOWTB 

(Unsigned external 

decimal table for 

class test) 

ILBOXDI 

(Decimal division) 

ILBOXMU 
(Decimal 
multiplication) 

ILBOXPR 

(Decimal fixed-point 
" '"exponent" I a tiohT J 
x 



Called by compiled 
code 

Used by ILBOCLS 



Called by compiled 
code and by ILBOXPR 



Called by compiled 
code and by ILBOXPR 

Called by compiled 
code 



150 



300 



300 



200 



700 



None 



None 



TT.ptn.qRU 



ILBOADR" 
ILBODBG" 



None 



None 



None 



None 



ILBOXDI 



300 



550 



300 
2000*- 




600 



3200 1 2 



150 



300 



300 



200 



300 



Notes : 



1. 


The 


2. 


The 


3. 


The 


4. 


The 




MFT 



5, 



6. 



7. 



9. 



reside in the MVT link pack area (LPA) or the 

(RRR). 

by subroutine ILBOCVB is used bv subroutine 



size given is an estimate. 

size given is a minimum. 

size given is a maximum. 

subroutine indicated may never 

resident reusable routine area 
The 256— byte storage area obtained 
ILBOUST. 

Because the ILBODBG subroutine dynamically loads and deletes subroutines as they 
are needed, depending on the options specified, it is possible only to estimate a 
minimum and/or a maximum amount of storage used by any one of the debugging 
options. For each storage estimate given below, the effect of possible core 
fragmentation is not considered. 

a. Basic debug package — 3100 bytes 

b. Debug with the STATE option — 3950 bytes 

c. Debug with the FLOW option — 8 92 bytes 

d. Debug with the SYMDMP option — 11,372 bytes minimum and 13,348 bytes maximuan 

e. Debug with dynamic dumps — 15,112 bytes minimum and 18,198 bytes maximum; 
(whenever a primary routine calls subroutine ILBODBG, the storage requirement 
is that for the basic package size) . 

The subroutine or dynamic work area indicated is obtained conditionally. 
The subroutine indicated is never called as a primary subroutine. 
The subroutine indicated must be on-line at execution time. 
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APPENDIX C: FIELDS OF THE DATA CONTROL BLOCK 



In this appendix, each field of the data 
control block is listed by the name of the 
operand of the assembler-language macro 
instruction that can specify a value for 
that field. Tables 36 through 40 
illustrate the data control blocks for 
sequential, direct, relative, and indexed 
files. Some of the data control block 
fields can be referred to with the DCB 
parameter of the DD statement. However, 
any field filled in by the COBOL compiler 
cannot be overridden except for the indexed 
file OPTCD field in which the 
L-subparameter is set by the compiler using 
DCB exit. 



Values for fields for which no entry 
appears in the column headed "COBOL Source" 
may be supplied by the DD statement or by 
the data set label. 

For information concerning the 
specification of values for data control 
block fields- see the DCB macro instruction 
for the different file processing 
techniques in the publication IBM O S 
Supervisor and Data Mana g ement Mac ro 
Instructions . 

Note : The DCB subparameters are discussed 
under "User Defined Files" in the chapter 
"User File Processing. " 
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Table 36. Data Control Block Fields for 
r t t- 



Standard Sequential Files 
T - 



| Data Control 
j Block Field 


Explanation of Field 


| Applicable 
j DD Statement 
COBOL Source j DCB Subparameters 


| BFALN 


Alignment 


(COBOL specifies double- | 
word boundary) | 


| BFTEK 


Buffering technique 
(S or E) 


(COBOL specifies S) | 


IBLKSIZE 


Maximum length of block 


BLOCK CONTAINS |BLKSIZE 
Data record description j 


| BUFCB 


Address of buffer pool 


SAME AREA | 


|BUFL 


Length of each buffer 




| BUFNO 


Number of buffers 
assigned to DCB 


RESERVE |BUFNO=N(default=2) 


| BUFOFF 




| (BUF0FF=[n|13 ) 


| DDNAME 


Name of DD statement 


ASSIGN clause j 


| DSORG 


Access method 


ASSIGN clause j 
ACCESS clause j 


| EODAD 


Address of user's end-of- 
data-set exit routine 
for input data set 


READ. . .AT END | 


| EROPT 


Error option 


| ( ER0PT= [ ACC | SKP | ABE] ) 


| EXLST 


Address of exit list 


Used by the compiler forj 
USE. . . LABEL, etc. j 


| LRECL 


Logical record length 


FD entry | LRECL 


|MACRF 


Type of macro instruction 


OPEN INPUT, READ | 
OPEN OUTPUT, WRITE | 
OPEN I-O, READ, WRITE j 
REWRITE | 


| OPTCD 


Optional service provided 
by control program 


| (OPTCD=[W|C|WC|I|Q] ) 


|RECFM 


Characteristics of 
records in data set 


RECORDING MODE | (RECFM=D) 
Record description j 
ADVANCING | 
POSITIONING | 
BLOCK CONTAINS | 
APPLY RECORD-OVERFLOW | 


| SYNAD 


Address of error exit 
routine 


Used by compiler for |RECFM={S|T> 
INVALID KEY and | 
USE AFTER ERROR j 



L J. -L X_. 



mo 



Table 37. Data Control Block Fields for Direct and Relative Files Accessed Sequentially 
r t t t 1 



j Data Control 
| Block Field 

L J 


Explanation of Field 

L J 


COBOL Source j 
I- 4. 


Applicable 
DD Statement 
DCB Subparameters 


r 1 
|BLKSIZE 


r 1 
Maximum length of block 


r T 
Data record description! 




Jddname 


Name of DD statement 


ASSIGN clause j 




| DSORG 


Access method 


ASSIGN clause j 
ACCESS clause j 






Address of end— of- data- set- 
exit (input) 


READ... AT END | 




| EXLST 


Address of exit list 


USE LABEL PROCEDURE | 




| KEYLEN 


Length of key 


ACTUAL KEY 1 | 
(length of j 
ACTUAL KEY - 4) j 




| LRECL 


Logical record length 


FD entry j 


LRECL 


| MACRF 


Type of macro instruction 


OPEN INPUT, READ | 
OPEN OUTPUT, j 
WRITE (DIRECT ONLY) j 




| OPTCD 


Optional service to be 
provided by control 
program 




[OPTCD=W|T] 


"j RECFM 


Characteristics of 
records in data set 


RECORDING- MODE - \. 

Record description | 
APPLY RECORD-OVERFLOW j 




| SYNAD 


Address of error exit 
routine 


USE AFTER ERROR | 
INVALID KEY j 





j ^-Direct 
l 



files only; for relative files, the field is 0. 
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Table 38. Data Control Block Fields for Direct and Relative Files Accessed Randomly 
r t t t 



j Data Control 
| Block Field 

I - —I 


Explanation of Field 

1- - J 


COBOL Source 

L 


| Applicable 
j DD Statement 
| DCB Subparameters 
i 


r I 
|BLKSIZE 


r 1 
Maximum length of block 


r 
Data record description 


T 


| DDNAME 


Name of DD statement 


ASSIGN clause 




| DSORG 


Access method 


ASSIGN clause 
ACCESS clause 




| EXLST 


Address of exit list 


USE... LABEL, etc. 




j KEYLEN 


Length of key for each 
physical record 


ACTUAL KEY 1 
( length of 
ACTUAL KEY - 4) 




| LIMCT 


Search limits 




|LIMCT=n (OPTCD=E 
J must be specified) 


|MACRF 


Type of macro instruction 


OPEN INPUT, READ 

OPEN OUTPUT, 

WRITE (DIRECT ONLY) 

OPEN 1-0, READ, 

WRITE (DIRECT ONLY), 

REWRITE 




| OPTCD 


Option service to be 

provided by the control 
program 




|OPTCD=E/W 


| RECFM 


Characteristics of 
records of data set 


RECORDING MODE 

APPLY RECORD-OVERFLOW 

Record description 




| SYNAD 


Address of error exit 
routine 


Used by compiler for 
INVALID KEY and 
USE AFTER ERROR 





1. i ± X .j 



I ^-Direct 

L. 



files only, for relative files this field is 0. 
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Table 39. Data Control Block Fields for 
r t 



Indexed Files Accessed Sequentially 

T T 



Data Control 
Block Field 

L 


j Explanation of Field 
L _ _ 


j COBOL Source 

L 


| Applicable | 

j DD Statement | 

DCB Subparameters j 

1- -4 


r 
BFALN 


r 

| Buffer alignment (F or D) 


r 

| (COBOL specifies D) 




BKLSIZE 


| Maximum length of block 


BLOCK CONTAINS 


BLKSIZE | 


BUFCB 


| Address of buffer pool 


|SAME AREA 




BUFNO 


[Number of buffers assigned 
to DCB 


| RESERVE 


BUFN0=N(default=2) | 


CYLOFL 


Number of overflow tracks 
for each cylinder 




CYL0FL=XX j 


DDNAME 


Name of DD statement 


ASSIGN clause 




DSORG 


Access method 


ACCESS clause 
ASSIGN clause 




EODAD 


Address of user's end-of- 
data-set exit routine 
for input data set 


READ... AT END 




EXLST 


Address of exit list 


Used by the compiler 




KEYLEN 


Length of key for each 
logical record 


RECORD KEY 




ERECE" 


Logical record~length 


FD entry 


LRECL - | 


MACRF 


Type of macro instruction 


OPEN INPUT, READ, START 
OPEN OUTPUT, WRITE 
OPEN 1-0, READ, START, 
REWRITE 




vimM 

IH J. L*l 


Maximum number of 

cylinder index tracks 




NTM=XX ' 


OPTCD 


Optional services 




OPTCD=I|R|W|Z|M|U|L j 
(must also have j 
NTM=M) j 


RECFM 


Characteristics of 
records in data set 


RECORDING MODE 
RECORD DESCRIPTION 
BLOCK CONTAINS 




RKP | 


Relative position of 

record key in logical | 
record 


RECORD KEY | 




SYNAD | 


Address of error exit | 
routine j 


Used by the compiler for 
INVALID KEY, j 
USE AFTER ERROR | 
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Table 40. Data Control Block Fields for Indexed Files Accessed Randomly 
r t t t 



Data Control 
Block Field 

j 


Explanation of Field 

L J 


COBOL Source 

L 


j Applicable 
| DD Statement 
|DCB Subparameters 


1 
BFA.LN 


r 1 
Buffer alignment (F or D). 


r 
(COBOL specifies D) 


T 


DDNAME 


Name of DD statement. 


ASSIGN clause 




DSORG 


Access method. 


ACCESS clause 
ASSIGN clause 




EXLST 


Address of exit list. 


Used by the compiler 




KEYLEN 


Key length. 


NOMINAL KEY 




LRECL 


Logical record length. 


FD entry 




MACRF 


Type of macro instruction. 


OPEN INPUT, READ 
OPEN I-O, READ, 
WRITE, REWRITE, 




MSHI 


Address of area for 
highest level index 
of data set. 


APPLY CORE-INDEX 




MSWA 


Address of area reserved 
for control program. 
Required for variable 
length records. 


TRACK-AREA 




SMS I 


Size for area provided for 
highest level index of 
the data set. 


APPLY CORE-INDEX 




SMSW 


Number of bytes reserved 
for main storage 
work area. 


TRACK- AREA 





L X J. ± J 



uin 



APPENDIX D: COMPILER OPTIMIZATION 



In general, compilation is faster when: 

1. Options in the EXEC statement are 
specified to: 

a. Make more main storage available 
(the SIZE option) 

b. Optimize the space available for 
buffers (the BUF option) 

c. Suppress output (the NOSOURCE, 
NODECK, NOLOAD, and the SUPMAP 
options, among others) 

d. Suppress object code if one or 
more E-level messages are 
generated. 

2. The maximum block size for a compiler 
data set is specified. 

3. A disk configuration and separate 
channels for utility data sets are 
used. 

U~. Separate -devices (i.e. -, not the same 
mass storage unit) on the same channel 
are used. 

Compilation time is also affected by the 
speed of the devices allocated to the data 
sets. For example, a tape device is faster 
than a printer for printed output. The 
blocking information that follows applies 
to MFT or MVT. 



• Specification of the COBOL Library 
Management Facility, via the RESIDENT 
compiler option, results in a saving of 
both main storage and secondary 
storage, as well as of time at the 
link-edit step and the initial program 
load for the program. 

• Dynamic invocation and release of COBOL 
subprograms, specified by the DYNAM 
compiler option, also results in 
savings in main storage. 

• A syntax checking compilation, 
specified by the SYNTAX or SYNTAX 
compiler option, saves machine time. 
Depending on which compiler options are 
chosen, as well as the various source 
program statements, compile time can be 
reduced by as much as 20% to 70%. 

The symbolic dump feature, specified by 
the SYMDMP option, can save much debugging 
time. However, use of this option can 
decrease performance expectations for 
programs run with it. That is, such 
programs-require additional- -t-ime— for the 
compile, link-edit, and execute job steps. 
They also require more main storage than 
programs run without this feature. 

For information about requesting any of 
these options, see the section "Options for 
the Compiler" in the chapter on "Job 
Control Procedures". 



BLOCK SIZE FOR COMPILER DATA SETS 



PERFORMANCE CONSIDERATIONS 



The OS Full American National Standard 
COBOL Compiler, Version 4, provides 
additional opportunities for saving either 
main storage or time. For example, 
specification of the Optimized Code 
Feature, the COBOL Library Management 
Feature, the Dynamic Subprogram Feature, or 
all three of these features, can result in 
a considerable saving in main storage. The 
notes given below provide additional 
performance information on programs run 
with these and other new features. 

* When the Optimized Code Feature is 
requested, via the OPTIMIZE compiler 
option, execution time is reduced for 
non-I/O bound programs; however, 
compilation time is increased. 



The blocking factor specified for 
compiler data sets other than utility data 
sets must be permissible for the device the 
data set is on. In addition, for the 
SYSLIN data set, it must be permissible for 
the linkage editor used. (Any block size 
specified for a utility data set in a DD 
statement is overridden by the compiler. ) 
If a block size other than the default 
option is needed, it can be requested by 
specifying the BLKSIZE subparameter of the 
DCB parameter in the DD statement for the 
data sets. The format of the subparameter 
is: 

DCB=(, BLKSIZE=nnn) 

where nnn is equal to N times the logical 
record size in bytes, and 1 < N < Yi. M is 
equal to the blocking factor permissible 
for the device, and, in the case of SYSLIN, 
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to the blocking factor permissible for the 
linkage editor used. 

If blocking is desired, the record 
format for SYSPRINT [DCB=(, RECFM=nnn) ] 
should be specified as FBA. The record 
format for SYSIN, SYSLIN, SYSPUNCH, and 
SYSLIB should be specified as FB. 

The logical record size for SYSPRINT is 
121 bytes. The logical record size for 
SYSIN, SYSLIN, SYSPUNCH, and SYSLIB is 80 
bytes. 

Note : For compile, link-edit, and execute 
cases when labeled volumes are used, RECFM 
and BLKSIZE must be given for SYSLIN in the 
compile step only. If BLKSIZE is specified 
for SYSPUNCH, LRECL must also be specified. 
The 44K version of the linkage editor 
supports input data sets with a blocking 
factor of up to 40 specified. 



HOW BUFFER SPACE IS ALLOCATED TO BUFFERS 



Once the amount of space available for a 
compilation is determined, the compiler 
subtracts the amount required for itself. 
From the space remaining, it then computes 
the space available for utility and 
input/output data set buffers. If space 
still remains, the compiler makes use of it 
for internal processing. 

Once the amount of space available for 
buffers is determined, the compiler 
calculates how this space is to be divided. 
First, it computes the amount of space 
required for the buffers of the 
input/output data sets. From the space 
remaining, it determines the maximum buffer 
size, and hence block size, possible for a 
utility data set. The utility data sets 
all have the same block size. Thus, the 
block size of a utility data set is 
dependent on the amount of space available 
for buffers. If a block size has been 
specified in a DD statement for a utility 
data set, it is overridden. 

A larger buffer size for a utility data 
set allows for faster processing. However, 
if the program being compiled takes up a 
large amount of the available storage, a 
smaller space for buffers enables the 
compiler to use more main storage for 
internal processing. 

The following describes how the space 
available for buffers is determined and how 
it is allocated to buffers. 

Let A represent the space that can be 
allocated to these buffers. It is 
determined as follows: 



1. If neither the BUF nor the SIZE option 
of the PARM parameter of the EXEC 
statement is specified, A equals the 
default value for buffer space. This 
value is specified at system 
generation time. The minimum value is 
2768 bytes except when BATCH is 
specified, when it is 2928 bytes. 



2. If the SIZE option is specified, but 
BUF is not, A equals (SIZE - 80K) / 4 
plus the default value for buffer 
space. 

3. If BUF is specified (whether or not 
SIZE is specified), A equals the value 
specified for BUF. 

Note: The minimum difference between 
SIZE and BUF must always be equal to 
or greater than the difference between 
the minimum SIZE value and the minimum 
BUF value (81920 bytes - 2768 bytes; 
or, when BATCH is specified, 81920 
bytes - 2928 bytes). 

4. If BUF is smaller than 2768, or for 
BATCH 2928, bytes (the minimum value), 
a warning message is printed and the 
minimum value is assumed. if BUF is 
too large to allow minimum table space 
for compilation, a warning message is 
printed and the default value (or the 
minimum value, if the default value is 
also too large) is assumed. 



The programmer must make sure that the 
amount of buffer space allocated by the 
system is sufficient, taking into consid- 
eration the block sizes specified for the 
compiler data sets. The allocated buffer 
space is divided as follows: 

1. Let B represent the amount of buffer 
space to be allocated for input/output 
data sets. B is computed as either 
equal to: 

2 times the block size of SYSPRINT + 
SYSIN + SYSLIB 

or 

2 times the block size of SYSPRINT + 
SYSPUNCH + SYSLIN 

whichever is larger. The maximum 
allowable value of B is A - 1280 
bytes. If the computed value is 
greater than the maximum allowable 
value, a diagnostic message is printed 
and compilation is abandoned. 

If the block sizes are not 
specified in the DD statements, the 
following default values are assumed: 
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Data Set 

SYSIN 

SYSLIN 

SYSPUNCH 

SYSLIB 

SYSPRINT 

SYSTERM 



Default 

Value (bytes) 

80 

80 

80 

80 

121 

121 



A - B 



If A < 6B, then C = 



If A > 6B, then C = - 

6 



Let C represent the amount of buffer 
space to be allocated for each utility 
data set. Therefore, C equals the 
block size of data sets SYSUTl- 
SYSUT2, SYSUT3, and SYSUT4, 
respectively. 



If C > maximum block size permitted 
for any device a utility data set is 
on, then the maximum block size is the 
value chosen for C. The minimum block 
size for a utility data set is 255 
bytes. 
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APPENDIX E; INVOCATION OF THE COBOL COMPILER AND COBOL COMPILED PROGRAMS 



The COBOL compiler can be invoked by a 
problem program at execution time through 
the use of the ATTACH or the LINK macro 
instruction, i.e., dynamic invocation. 
Dynamic invocation of COBOL compiled 
programs can be accomplished through the 
use of the LINK or the LOAD macro 
instruction. 



INVOKING THE COBOL COMPILER 



The problem program must supply the 
following information to the COBOL 
compiler: 

• The options to be specified for the 
compilation 

• The ddnames of the data sets to be used 
during processing by the COBOL compiler 

• The header to appear on each page of 
the listing 



Name 



-T T 

| Operation | Operand 



I- 

| [symbol] | LINK 
I I ATTACH 



H 



|EP=IKFCBL00, | 

|PARAM=(optionlist | 
j [, ddnamelist] , j 
| [,headerlist]),VL=l | 

.j. j 



where: 



EP 



specifies the symbolic name of the 
COBOL compiler. The entry point at 
which execution is to begin is 
determined by the control program 
(from the library directory entry). 



PARAM 



specifies, ac a sublist, address 
parameters to be passed from the 
problem program to the COBOL compiler. 
The first fullword in the address 
parameter list contains the address of 
the COBOL option list. The second 
fullword contains the address of 
ddname list. If standard ddnames are 
to be used and no header list is 
specified, this list may be omitted. 
If standard ddnames are to be used and 
a header list is specified, this entry 
should contain the address of a word 
of binary zeros, aligned on a 
halfword. The last fullword contains 
the address of the header list. This 
list may be omitted. 



option list 

specifies the address of a variable 
length list containing the COBOL 
options specified for compilation. 
For additional details, see the 
description of the EXEC statement in 
the chapter "Job Control Procedures. " 
This address must be written even 
though no list is provided. 



The option list must begin on a 
halfword boundary. The two high-order 
bytes contain a count of the number of 
bytes in the remainder of the list. 
If no options are specified, the count 
must be zero. The option list is free 
form with each field separated from 
the next by a comma. ifo blanks or 
zeros should appear in the list. 



ddname list 

specifies the address of a variable 
length list containing alternative 
ddnames for the data sets used during 
COBOL compiler processing. If 
standard ddnames are used, this 
operand may be omitted. 

The ddname list must begin on a 
halfword boundary. The two high-order 
bytes contain a count of the number of 
bytes in the remainder of the list. 
Each name of less than eight bytes 
must be left justified and padded with 
blanks. If an alternate ddname is 
omitted from the list, the standard 
name will be assumed. If the name is 
omitted within the list, the 8-byte 
entry must contain binary zeros. 
Names can be omitted from the end 
merely by shortening the list. 

The sequence of the 8-byte entries in 
the ddname list is as follows: 



ddname 


Name for 


8-byte 


Entry 


Which Substituted 


1 




SYSLIN 


2 




not applicable 


3 




not applicable 


4 




SYSLIB 


5 




SYSIN 


6 




SYSPRINT 


7 




SYSPUNCH 


8 




SYSUT1 


9 




SYSUT2 


10 




SYSUT3 


11 




SYSUTU 


12 




SYSTERM 


13 




SYSUT5 
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header list 

specifies the address of a 
variable-length list containing 
information to be included in the 
heading on each page of the listing. 
The list must begin on a halfword 
boundary. The two high-order bytes 
should contain a count of the number 
of bytes in the new heading 
information; the next four bytes of 
the list should contain the page 
number at which the heading is to 
start, in EBCDIC format. 



When the COBOL compiler completes 
processing, a return code is placed in 
register 15. For additional details, see 
the discussion of the COND parameter in the 
chapter "Job Control Procedures. " 



INVOKING COBOL COMPILED PROGRAMS 



specified as follows: 



VL 



specifies that the sign bit is to be 
set to 1 in the last fullword of the 
address parameter list. 



1. For the PROGRAM-ID program-name, a 
NAME card. 

2. For each ENTRY literal-1, an ALIAS 
card should be specified in a COBOL 
program that is to be dynamically 
invoked. 
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APPENDIX F: SOURCE PROGRAM SIZE CONSIDERATIONS 



Limitations on the size of a COBOL 
source program should be considered in 
relation to the capacities of both the 
COBOL compiler and the various linkage 
editors. This appendix contains 
information to aid the programmer in 
determining how his source program affects 
usage of space at compilation time and 
linkage editing time. 



COMPILER CAPACITY 



The capacity of the COBOL compiler is 
limited by two general conditions: (1) the 
total contiguous space available must be 
sufficient for compilation and (2) an 
individual table may not have a length 
greater than 32,767 bytes, with the 
exception of the ADCON and cross-reference 
tables. If either of these conditions is 
not met during compilation, one of the 
following error messages will be issued: 

IKF0001I-D SIZE PARAMETER TOO SMALL FOR 
THIS PROGRAM. 

IKF0010I-D A TABLE HAS EXCEEDED THE MAXIMUM 
PERMISSIBLE SIZE. 

In either case, compilation is terminated. 
However, in the first case, the program may 
be recompiled with a larger SIZE parameter. 
The size of the ADCON and cross-reference 
tables is not limited to 32,767 bytes. 

If a table overflows, the following error 
message will be generated, and the user 
will need to rerun the program in a larger 
region. 

IKF6007I-D TABLE OVERFLOW. PMAP LOAD 
MODULE OR DECK WILL BE 
INCOMPLETE. INCREASE SIZE 
PARAMETER. 



Mini m um Configuration SOURCE PROG RAM Size 



exception of SYSOUT for which 120 bytes are 
allocated. Double buffering will be 
assumed. 

Within this configuration, assuming no 
REPORT SECTION, the compiler will accept: 

• Three hundred procedure references 
assuming an average procedure-name 
length of 12 characters 

• Twenty-five OCCURS clauses with the 
DEPENDING ON option 

• Ten files assuming an average of three 
subordinate record entries 

• Four hundred literals assuming an 
average of eight bytes 



EFFECTIVE STORAGE CONSIDERATIONS 



The amount of core storage within the 
compiler's partition and the limitation on 
the size of an individual internal table 
are two factors that limit the capacity of 
the compiler. The limitation on the size 
of internal tables can, in some instances, 
be overcome by the spilling over of some 
tables onto external devices. However, 
spilling over may cause a severe 
degradation of performance. The core 
storage limitation should not be reached by 
any reasonable use of the language. 
However, within a limited storage capacity 
excessive use of certain features and 
combination of features in the language 
could make compilation impossible. Some of 
the features that significantly affect 
storage usage are the following: 

1. ADCON_Table 

Each entry occupies 8 bytes. This 
table is not limited to the maximum 
size of 32,767 bytes. Entries are 
based on the: 



The compiler will accept and compile a 
1500 card program in the minimum machine 
configuration (80K). Within an 80K byte 
environment, the user should not specify 
buffer size for the compiler files. Of 
course, the various reader procedures may 
affect the value required for SIZE and BUF 
parameters. The compiler will allocate the 
minimum required amounts that are 256 bytes 
for each of the 4 intermediate files, 8 
bytes for each system file with the 



• Number of 4096-byte segments in the 
Working-Storage Section 

• Number of 4096-byte segments in a 
file buffer area 

• Number of referenced procedure- names 

• Number of implicit procedure-name 
references such as those generated 
by IF, SEARCH, and GENERATE 
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statements, ON SIZE ERROR, INVALID 
KEY, and AT END options, the OCCURS 
clause with the DEPENDING ON option, 
USE sentences, and the Segmentation 
feature. 



• Number of files 



2. Procedure-name Table 



• One byte for each character in a 
numeric edited or alphanumeric 
edited item picture 

• Five bytes for an elementary item 
with a Sterling Report picture 
clause 

• Three bytes for an item subordinate 
to an OCCURS clause 



This table contains the number of 
definitions written in a section and 
unresolved procedure references. 
Procedure references are resolved at 
the end of a section if the definition 
of the procedure-name is in that 
section or a preceding section. 
Therefore, forward references beyond a 
section impact space. Approximately 
900 unqualified entries are possible. 
A maximum number of 16, 255 entries may 
be specified. 

3. OCCURS DEPENDING O N Table 

This table contains an entry for 
each unique object of an OCCURS clause 
with the DEPENDING ON option. The 
size of an entry is 2 + length of name 
+ length of each qualifier bytes. 

4. Index Table- 

An entry is made for each INDEXED 
BY clause consisting of 11 bytes for 
each index. 



8 . Litera l Tables 

The total length of all literals 
may not exceed 32511 bytes. No more 
than 16255 literals may be specified. 

9 . Mis cella n eous Tables 

The presence of the following items 
causes entries to be made into tables 
that affect the total space required 
for compilation. 



SAME [RECORD] AREA clause 

Subscripting 

Intermediate Arithmetic Results 

Complex Arithmetic Expressions 

Complex Logical Expressions 

APPLY clauses 

Special-Names 

RERUN clauses 

Error- messages. 

XREF 

Segmentation feature 



5. File Table 



An entry is made for each file 
specified in the program. Each entry 
occupies 60 bytes of storage. 

6 . Report Writer Tables 

A considerable amount of 
information is maintained for each RD 
such as controls, sums, headings, 
footings, routines to be generated, 
and so on. The contents of the table 
are increased by qualification and 
subscripting in the Report Section. 
Approximately 30 reports can be 
processed without exceeding the limit 
of the table. 

7. Dictionary Table 

An entry is made for each 
procedure-name and each data-name in 
the program. A procedure entry 
consists of (7 or 9 + length of name) 
bytes. A data entry consists of 
(length of name + n) bytes, where n is 
determined by the attributes of the 
data item. Some of the features that 
contribute to the value n are: 



LINKAGE EDITOR CAPACITY 



Some COBOL program and linkage editor 
considerations are listed below as a 
further guide in preparing a source 
program. Consult the publication IBM OS 
Linkage Editor and Loader, for additional 
information on linkage editor capacities 
and processing. 

1. All COBOL object programs, with the 
exception of segmented programs, 
consist of a single CSECT (control 
section) . The size of the object 
module may be determined by looking at 
the location of the last instruction 
in INIT3 in the object code listing 
(see the section entitled "Output") or 
from the END card. 

2. The size of the object module is 
greatly increased by any of the 
following: 

a. The blocking factor and alternate 
area reservation of randomly 
accessed files 
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b. The specification of the SAME AREA 
clause for sequentially accessed 
files 

3. RLD (Relocation List Dictionary) cards 
are part of the load module, and are 
used by the linkage editor to compute 
the address constants for the load 
module. The number of RLDs produced 
by the compiler can be determined by 
the following formula : 

number of RLDs = number of unique 

subprograms called + number of COBOL 
library routines called + number of 
nonresident segments 



4. The output text of the compiler is 

written out in a sequence that differs 
from the order indicated by the 
location counters contained in each 
output item. This sequence difference 
may result in a strain on the 
facilities of the linkage editor. 



5. VALUE clauses in the Working-Storage 
Section may result in many 
discontinuous text records. 

6. The object module produced by the 
COBOL compiler may not be sorted prior 
to the linkage editor step. 
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APPENDIX G: INPUT/OUTPUT ERROR CONDITIONS 



This appendix contains a brief summary 
of input/output (I/O) error conditions for 
each of the file processing techniques. 
More detailed information on error 
conditions can be found in the following 
publications: 

I BM OS Supervisor and Data Mana gement 
Macro Instructions 

IBM OS System Control Blocks 



• I/O E rror Conditions: 

1. Record Not Found 

2. Invalid Request 

a. Requested block outside data set. 

b. Attempt to add fixed-length record 
with key beginning with 
hexadecimal FF. 



STANDARD SEQUENTIAL, DIRECT, AND RELATIVE 
FILE PROCESSING TECHNIQUE (SEQUENTIAL 
ACCESS) 



Register 1 contains error bits 
indicating the exact cause of an error. 
Conditions causing input/output errors and 
suggested user responses are as follows: 

• I/O Error Conditions : 

1. Input Error 

2. Output Error 

3. Invalid Request (BSAM only) 

Suggested User Response : 

For BSAM, display the error message. 
Processing of the file is limited to CLOSE. 
For QSAM, display the error message and 
then execute the EROPT option in the DD 
statement. Note that the EROPT option 
gives the user three choices: 

• ACC - Accept the error block and 

continue processing 

• SKP - Skip to the next block. 

• ABE - Terminate the job. 



DIRECT AND RELATIVE FILE PROCESSING 
TECHNIQUE (RANDOM ACCESS) 



The DECB contains two error condition 
bytes at location DECB +4. Conditions 
causing input/output errors and suggested 
user responses are as follows: 



Suggested User Response : 

Condition caused by invalid key. 
Processing of the file may be continued. 



• I/O Error Condition 

Space Not Found 

Suggested User Re spon se : 

Processing of the file may be continued. 
CLOSE, READ, or REWRITE statements may be 
executed for the file. 

• I /O Error Conditi ons: 

1. Uncorrectable I/O Error 

2. Uncorrectable Error, Not I/O 
Suggested User Response : 

Processing of the file is limited to CLOSE, 



INDEXED FILE PROCESSING TECHNIQUE 
(SEQUENTIAL ACCESS) 



The DCB contains two error condition 
bytes named EXCD1 and EXCD2, at location 
DCB + 80. Conditions causing I/O errors 
and suggested user responses are as 
follows: 

• I /O Error Conditions : 

1. Sequence Check 

2. Duplicate Record 

Sugge sted Us er Response : 

Condition caused by INVALID KEY. 
Processing of the file may be continued. 
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• I/O Error Co ndit ions : 

1. Space Not Found 

2. Uncorrectable Output Error 
3- Unreachable Block (Input) 
4. Unreachable Block (Update) 

Suggested User Response : 

Processing of the file is limited to CLOSE. 

• I/O Error Conditions : 

Uncorrectable Input Error 

Sugg ested User .Response : 

The user may attempt to bypass the block 
containing the error. If, in reading the 
next block, the error does not recur, he 
may continue processing without closing the 
file. If the error persists, processing of 
the file is limited to CLOSE. 



INDEXED FILE PROCESSING TECHNIQUE (RANDOM 
ACCESS) 



The DECB contains an error condition 
byte at location DECB + 24. Conditions 
causing I/O errors and suggested user 
responses are as follows: 

• I/O Error Condition : 

1. Record Not Found 

2. Duplicate Record 



Sug gested User Response : 

Condition caused by INVALID KEY. 
Processing of the file may be continued. 

• I/O Error Condition : 

Space Not Found 

Suggest ed User Response : 



Processing of the file may be continued. 
The record may be written after changing 
the keys and executing a WRITE statement if 
a cylinder overflow area is available for 
the new value of the keys. CLOSE or READ 
may be executed for the file. 



• I /O Error Condition : 
Invalid Request 
Sug gested Use r R es po nse : 

Processing of the file is limited to CLOSE. 

• I /O Error Conditions: 

1. Uncorrectable I/O Error. 

2. Unreachable Block — Index Cannot Be 
Read. 

Sug gest ed User Response : 

Processing of the file is limited to CLOSE. 
The user can try to execute the instruction 
again. If the error persists, he can close 
the file or perform file recovery 
procedures. 
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APPENDIX H; C REATING AND RETRIEVING INDEXED SEQUENTIAL DATA. SETS 



Indexed data sets are created and 
retrieved using special subsets of DD 
statement parameters and subparameters. 
They can occupy up to three different areas 
of space: 

• Prime Area — This area contains data 
records and related track indexes. It 
exists for all indexed data sets. 

• Overflow Area — This area contains 
overflow from the prime area when new 
data records are added. It is 
optional. 

• Index Area — This area contains master 
and cylinder indexes associated with 
the data set. It exists for any 
indexed data set that has a prime area 
occupying more than one cylinder. 



Indexed data sets must reside on mass 
storage volumes. Because an Indexed data 
set can be associated with more than one 
type of unit, it is not usually cataloged. 



Creating an Indexed Data Set 

Indexed data sets are created with from 
one to three DD statements. One of the 
statements must define the prime area. If 
additional areas are to be defined, the DD 
statements must appear in the following 
seguence: 

1. Index area 

2. Prime area 

3. Overflow area 



DSNAME : Reguired. In addition to giving 
the data set name, the DSNAME parameter 
identifies the area being defined, i. e. , 
DSNAME=name ( INDEX) , DSNAME=name ( PRIME ) , 
and DSNAME=name (OVERFLOW) . 

Notes: 

• If the data set is temporary, name 
is replaced with &6name. 

• If only one DD statement is used to 
define the entire data set, 
DSNAME=name (PRIME) or DSNAME=name 
should be used. 



UNIT : Reguired, unless VOLUME=REF is used. 
The first subparameter identifies a mass 
storage unit. If separate statements 
for the prime and index areas are 
included, reguest the same number of 
units for the prime area as there are 
volumes. The DEFER subparameter cannot 
be specified on any of the statements. 
Another way of reguesting units is by 
-using__the_unit_ af f i nit y _ s ubpar ame t er , 
AFF. " 

Notes: 

• DD statements for prime and overflow 
areas must indicate the same type of 
unit. 

• The DD statement for the index area 
can indicate a unit type different 
than the others. 



VOLUME: Optional. Can be used to reguest 
private volumes (PRIVATE) , to retain 
private volumes (RETAIN), or to make 
specific volume references (SER or REF) , 



This order must be maintained even if one 
of the statements is absent. Only the 
first DD statement defining the data set 
can contain a name field. Other 
statements, if any, must have a blank name 
field. 

The subset of DD statement parameters 
used to create an indexed data set excludes 
the asterisk, DATA, DUMMY, DDNAME, SYSOUT, 
SUBALLOC, and SPLIT parameters. The 
remaining DD statement parameters — 
DSNAME, UNIT, VOLUME, LABEL, DCB, DISP, 
SPACE, SEP, and AFF — are all valid. 
However, certain restrictions must be 
followed in using these parameters. 



LABEL: Optional. Can be used to specify a 
retention period (EXPDT or RETPD) and/or 
password protection (PASSWORD). 



DCB : Reguired. Can be used to complete 
the data control block if it has not 
been completed by the processing 
program. Either DSORG=IS or DSORG=ISU 
must be included in the list of 
attributes, even though this attribute 
was provided in the processing program. 
If more than one DD statement is used to 
define the data set, the DCB parameters 
in the statements must not contain 
conflicting attributes. 
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DISP: Optional. Must be coded to keep the 
data set (KEEP), to catalog it (CATALG) , 
or to pass it to a later job step 
(PASS). An indexed data set can be 
cataloged using CATLG only if all three 
areas are defined by the same DD 
statement. 

Note: 

• Indexed data sets defined by more 
than one DD statement can be 
cataloged by using the system 
utility program IEHPROGM, provided 
all volumes reside on the same type 
of unit. The utility program 
IEHPROGM is described in the 
publication IBM OS Utiliti es. 

SPACE : Required. Space must be requested 
using either the recommended nonspecific 
allocation technique or the more 
restricted absolute track (ABSTR) 
technique. All DD statements used to 
define the data set must request space 
using the same technique. 

If the nons pecific space allocation 
technique is used, space must be 
requested in units of cylinders (CYL). 
The quantity of space requested is 
assigned to the area identified in the 
DSNAME parameter. If more than one unit 
is requested, this quantity of space is 
allocated to each volume used by the 
data set. Incremental space cannot be 
requested for indexed data sets. If one 
DD statement is used to define both the 
index and prime areas, the size of the 
index must be indicated in the SPACE 
parameter of the DD statement defining 
the prime area. The subparameters RLSE, 
MXIG, ALX, and ROUND cannot be used. 
Contiguous space can be requested on 
each of the volumes occupied by the data 
set with the subparameter CONTIG. If 
CONTIG is coded on one of the 



statements, it must be coded on all of 
them. 

If the absolute track technique of 
allocating space is used, the number of 
tracks must be equivalent to an iutegral 
number of cylinders* The address of the 
beginning track must correspond with the 
first track of a cylinder other than the 
first cylinder on a volume. If more 
than one unit is requested, space is 
allocated beginning at the specified 
address and continuing through the 
volume and onto the next volume until 
the request has been satisfied. If one 
DD statement is used to define both the 
index and prime areas, indicate the size 
of the index (in tracks) in the SPACE 
parameter of the DD statement defining 
the prime area. This number must also 
be equivalent to an integral number of 
cylinders. 

Notes: 

• The first volume to be allocated for 
the prime area of an indexed data 
set cannot be the volume from which 
the system is loaded (the IPL 
volume) . 

• Space can be requested on more than 
one volume only on the DD statement 
that defines the prime area. 

S EP AND AFF : Optional. Channel separation 
from earlier data sets can be requested 
on any of the DD statements in the 
group. In order to have areas of an 
indexed data set written using separate 
channels, units should be requested by 
their actual address (e.g., UNII=190). 

Figure 120 illustrates a valid set of DD 
statements for creating an indexed data 
set. Note that each area is defined by a 
separate DD statement. 



| //OUTPUTS DD DSNAME=MHB ( INDEX) , UNI T=2 301, DCB=DSORG=IS, 
| // SPACE= (CYL, 10, , CONTIG) , DISP= ( , KEEP) 



I// 

I// 

I// 

I 

I// 

I// 

L 



DD DSNAME=MHB (PRIME) , DCB=DSORG=IS, UNIT= (2311,2), 
VOLUME=SER=( 334, 335), DISP=(, KEEP), 
SPACE= (CYL, 25, , CONTIG) 

DD DSNAME=MHB(OVFLOW) ,DCB=DSORG=IS,UNIT=2311, 

VOLUME=SER=336, SPACE= (CYL, 25, , CONTIG) , DISP= ( , KEEP) 



Figure 120. Creating an Indexed Data Set 
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Table 41. Area Arrangement for Indexed Data Sets 



CRITERIA 



Number of 
DD Statements 



Types of 
DD Statements 



T 1 

Index Size 
Coded? 



Restrictions on 

Unit Types and 

Number of Units 

Requested 



Resulting 

Arrangement 

of Areas 



INDEX 
PRIME 
OVFLOW 



PRIME and OVFLOW 
must specify the same 
unit type. 



Separate index, 
prime, and overflow 
areas. 



INDEX 
PRIME 



None 



Separate prime and 
overflow areas, with 



. j ,.„ ., j 



-U „ «_ J 



an 111UC& cxi- me cu^ 

of the prime area. 



PRIME 
OVFLOW 



NO 



Both statements must 
specify the same type 
of unit. 



Prime area and over- 
flow area with an 
index at its end. 



PRIME 
OVFLOW 



Yes 



Both statements must 
specify the same unit 
type. The statement 
defining the prime 
area cannot request 
more than one unit. 



Prime area with em- 
bedded index and 
overflow area. 



PRIME 



No 



None 



Prime area with index 
at its end. Unused 
index areas, if any, 
used for overflow. 
.j 

Prime - area with " j" 
embedded index area, j 



PRIME 



Yes 



Cannot request 
more than one unit. 



The manner in which the areas of an 
indexed data set are arranged is based 
primarily on two criteria: 



• The number of DD statements used to 
define the data set. 

• The types of DD statements used (as 
reflected in the DSNAME parameter). 



An additional criterion arises when a DD 
statement is not included for the index 
area: 

• The index size and whether or not it 
has been coded in the SPACE parameter 
of the DD statement defining the prime 
area. 



Table 41 illustrates the arrangements 
resulting from various permutations of the 
foregoing criteria. In addition, it points 
out restrictions on the number and type of 
units that can be requested for each 
permutation. 



Retrieving an Indexed Data Set 

Indexed data sets are retrieved with the 
DD statement parameters DSNAME, UNIT, 
VOLUME, DCB, and DISP. Channel separation 
requests can be made using the SEP and AFF 
parameters. If all areas of the data set 
reside on the same type of unit, the entire 
data set can be retrieved with one DD 
statement. If the index resides on a 
different type of unit, two DD statements 
must be used. 

DSNAME: Required. Identify the data set 
by its name. If it was passed from a 
previous step, identify it by a backward 
reference or its temporary name. Do not 
include the terms INDEX, PRIME, or 
OVFLOW. 

UNIT: Required, unless the data set was 
passed on one volume. Identify the unit 
type. If the data set resides on more 
than one volume and all units are the 
same type, request the total number of 
units required by all areas. If the 
index area resides on a different type 
of unit, use two DD statements, each 
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indicating the number of units of the 
specified type required. 

VOLUME: Required, unless the data set was 
passed on one volume. Identify the 
volumes by their serial numbers (SER), 
listed in the same sequence as they were 
when the data set was created. 



was not completed in the program. 
Include either DSORG=IS or DSORG=ISU. 



DISP: Required. Identify the data set as 
OLD or MOD and give its new disposition, 
to change its disposition. 



DCB ; Required, unless the data set was 
passed. This parameter is used to 
complete the data control block if it 



Figure 121 shows how to retrieve the 
indexed data set created by the 
illustration in Figure 120. 



| //INPUT DD DSNAME=MHB,DCB=DSORG=IS,UNIT=2301,DISP=OLD 

|// DD DSNAME=MHB,DCB=DSORG=IS,UNIT=(2311,3),DISP=OLD, 

j// VOLUME=SER=(334,335,336) 



Figure 121. Retrieving an Indexed Data Set 
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APPENDIX I: CHECKLIST FOR JOB CONTROL PROCEDURES 



This checklist illustrates general job 
control procedures for compiler, linkage 
editor, and execution processing. More 
than one example may be used for a job 
step. The checklist is intended as an aid 
to preparing procedures, not as an 
inclusive list of the options and 



If the DD * convention is used, the 
SYSIN DD statement must be the last DD 
statement for the job step, and the source 
module must follow. If another job step 
follows the compilation, the EXEC statement 
for that step follows the /* statement. 



yen. amc LCi.a. 



COMPILATION 



Figure 122 shows a general job control 
procedure for a compilation job step. The 
following cases demonstrate how to add to 
or modify the general procedure to obtain 
various processing options. 



Case 3: Object Module Is to Be Pu nched 



Add txie statement: 



//SYSPUNCH DD SYSOUT=B 



Case 1: Compilation Only — - No Ob ject 
Module Is to Be Produced 



The general procedure should be used. A 
listing is produced. It will include the 
default" or specif ied options of the PARM - 
parameter that affect output. Any 
diagnostic messages are listed, unless 
listing of warning messages is suppressed 
by the FLAGE option of the PARM parameter 
and only warning messages are produced. 



Case - 2 : Source Module from Card Reader 



Modify the end of the procedure as 
follows: 

//SYSIN DD * 

(source module) 
/* 



Note: If DECK is not the installation 
default condition, it must be specified in 
the PARM parameter of the EXEC statement. 



Case Hz Obje ct Module Is to Be Passed to 
Li nkage Editor 



Add the statement: 

//SYSLIN DD DSNAME=(subparms), X 

// UNIT=SYSDA, X 

// SPACE=(subparms) , X 

// DISP=( MOD, PASS) 

Note : If LOAD is not the installation 
default condition, it must be specified in 
the PARM parameter of the EXEC statement. 



j//jobname JOB ace tno, name, MSGLEVEL=1 

|//stepname EXEC PGM=IKFCBL00, PARM= ( options) 

J //SYSUT1 DD UNIT=SYSDA, SPACE= ( subparms ) 

| //SYSUT2 DD UNIT=SYSDA, SPACE= ( subparms ) 

j //SYSUT3 DD UNIT=SYSDA, SPACE= ( subparms ) 

1//SYSUT4 DD UNIT=SYSDA,SPACE=( subparms) 

|//SYSPRINT DD SYSOOT=A 

j //SYSIN DD DSNAME=dsname,UNIT=SYSSQ,VOLUME= (subparms), 

j // DISP= (OLD, DELETE) 



Figure 122. General Job Control Procedure for Compilation 
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Case 5; object Module Is to Be Saved 



The object module can be saved by 
cataloging it, by keeping it, or by adding 
it as a member of a library. Add the 
SYSLIN statement as shown in examples A., B, 
or C. 



• A. Cataloging 

//SYSLIN DD DSNAME=dsname, 

NEW 
// DISP=( , CATLG), 

MOD 
// VOLUME= ( subparms ) , 

// LABEL= ( subparms ) , 

SYSDA 
// UNIT= , 

SYSSQ 



// 



SPACE 

SPLIT =( subparms) 

SUBALLOC 



C. Both BASIS and COPY 

//SYSLIB DD DSNAME=basislibname,DISP=SHR 

// DD DSNAME=copylibname,DISP=3HR 

(DD statements for additional copylibs may 
follow. ) 



LINKAGE EDITOR 



Figure 123 shows a general job control 
procedure for a linkage editor job step. 
The following cases show how to add to or 
modify the procedure to obtain various 
processing options. 



Case 1: Input from Previous Compil ation in 
Same Job 



• B. Keeping 



//SYSLIN DD DSNAME=dsname, 

NEW 
// DISP=( , KEEP), 

MOD 
// VOLUME= ( subparms ) , 

/ / LABEL= ( s ubpa rms ) , 

SYSDA 
// UNIT= , 

SYSSQ 



Change the SYSLIN statement to 

//SYSLIN DD DSNAME=*.stepname. SYSLIN, : 
// DISP= (OLD, DELETE) 

where stepname is the name of the previous 
compilation job step and ddname is SYSLIN. 
If the input is to be saved, specify KEEP 
rather than DELETE. 



// 



SPACE 

SPLIT =( subparms) 

SUBALLOC 



• C. Adding a Member to an Existing 
Library 

//SYSLIN DD DSNAME=dsname( member), 
// DISP=OLD 



Case - 6 : C O PY Sta t ement in COB OL Source 
M odu l e or a BAS IS Card in the Input Stream 

Add the SYSLIB DD card(s), as shown in 
examples A, B, or C. 

A. COPY 

//SYSLIB DD DSNAME=copylibname,DISP=SHR 

B. BASIS Card 

//SYSLIB DD DSNAME=basislibname,DISP=SHR 



Case 2 ; Input from Card R eader 



Change SYSLIN statement and the end of 
the procedure as follows: 

//SYSLIN DD * 

(object module (s)) 
/* 

If the DD * convention is used, the 
SYSLIN DD statement must be the last DD 
statement in the job step. If another job 
step follows the link-edit step, the EXEC 
statement for that job step follows the /* 
statement. 



Case_3: Input _Not_f rom_Compilation_in_Same 

Job 



Specify in the SYSLIN DD statement where 
the object modules to be used as input are 
stored. (Only one member of a library can 
be specified in the SYSLIN DD statement. ) 
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//jobname JOB acctno, name,MSGLEVEL=l 



//stepname EXEC P GM= I EWL, PARM= (options) 

//SYSPRINT DD SYSOUT=A 

//SYSLMOD DD DSNAME= 6 Sname (member) , UNIT=SYSDA, DISP=(NEW, PASS) , X 

// SPACE= ( subparms ) 

//SYSLIB DD DSNAME=SYSl.COBLIB, DISP=OLD 

//SYSUT1 DD UNIT=SYSDA, SPACE=(subparms) 

//SYSLIN DD DSNAME=dsname,DISP=OLD 

General Job Control Procedure for a Linkage Editor Job Step 



Case 4 : Output to Be Placed in Li nk 
Library 



Change the SYSLMOD statement as follows : 

//SYSLMOD DD DSNAME=SYS1. LINKLIB (member) , X 
// DISP=OLD 

where member is the name of the load module 
that is to be added to the link library. 
No other information is needed in the 
statement. 



EXECUTION TIME 



Figure 124 shows a general job control 
procedure for an execution-time job step. 
The following cases show how to add to or 
modify the general procedure to obtain 
various processing options. 



Case_lj Loa d Module to Be Executed Is in 

Link Library 



Case 5: Output to Be Placed in Pri vate 
Library 



Change the SYSLMOD statement as follows: 

//SYSLMOD DD DSNAME=dsname ( member ) . X 
// DISP=OLD 

where member is the name of the load module 
to be added, and dsname is the name of an 
existing library. If the library is not 
cataloged, UNIT and VOLUME parameters must 
be specified. 

Note: See "Using the DD Statement" for an 
example of creating a new library and 
storing the load module as its first 
member. 



Use the general procedure, where 
progname in the EXEC statement is the 
member name of the load module. 



Cas e 2: Load Module to Be Execute d Is a 
Membe r of Private Library 



The JOBLIB statement must follow the JOB 
statement, as in the following statements: 



//J0B1 


JOB 




//JOBLIB 


DD 


DSNAME=MYLIB, 


// 




DISP=( OLD, PASS) 


//STEP1 


EXEC 


PGM=PAYROLL 



Case 6: O utput t o B e Used Only in this Job 



The general procedure should be used. 
The load module is stored in a temporary 
library. 



//STEP2 



EXEC PGM=ACCOUNT 
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I //stepname EXEC PGM=progname 

j //ddname DD (parameters for user-specified data sets) 



Figure 124. General job Control Procedure for an Execution-Time Job Step 



The JOBLIB statement defines the private 
library MYLIB. No volume or unit 
parameters are given since the library is 
cataloged. Since JOBLIB has the 
disposition PASS, both steps can execute 
members of the library named in the JOBLIB 
statement. If only the first step executes 
a load module from the library, the 
disposition PASS on the JOBLIB statement 
need not be included. 



Case 3: Load Modu le to Be Execu ted Is 
Cr ea t ed in Previou s Linka ge E ditor Step in 
Same Job 



Change the EXEC statement as follows: 



//stepname EXEC PGM=*. stepname. SYSLMOD 



where stepname following PGM is the name of 
the linkage editor job step that created 
the load module. 



Case 6: DISPLAY UPON SYSP UNCH Is Included 
in Source Module 

Add the statement: 
//SYSPUNCH DD SYSOUT=B 



Case 7: ACCEP T Is Included i n Sou rce 
Module 



If the data is in the input stream, add 
the statement: 

//SYSIN DD * 

(data) 

/* 

(See Case 2 under "General Job Control 
Procedures for a Compilation Job Step" for 
a discussion of the DD * convention. ) 



Case 8: Debug_Statements_EXHIBIT_or_TRA.CE 

Are Included in Source Module 



Case 4: Abnormal Termination D um p 

Add the statement: 
//SYSABEND DD SYS0UT=A 



This statement requests a full dump if 
abnormal termination occurs during 
execution. 



Use the statement (unless it is already 
included) : 

//SYSOUT DD SYS0UT=A 

Not e: If the job step already includes a 
SYSOUT DD statement for some other use, 
another need not be inserted. 



Case 9: Object Time Symb olic Debugging 
Opt ions 



Case 5 : DI SPLAY Is Included in So urce 
Module 

Add the statement: 
//SYSOUT DD SYS0UT=A 



//SYSDBOUT DD SYS0UT=A required for all 

options 
//SYSDBG DD * required for SYMDMP 

option 
(control cards) 
/* 

debug DDname card also needed 
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APPENDIX J: FIELDS OF THE GLOBAL TABLE 



In this appendix, each field of the Task 
Global Table (Figure 125) and of the 
Program Global Table (Figure 126) is listed 
by its relative location in main storage. 
Each field is further described in the 
discussion associated with Figures 125 and 
126. 



TASK GLOBAL TABLE 



The Task Global Table (TGT) is used to 
record and save information needed during 
execution of the object program. It begins 
with a series of fixed-length fields 
followed by a series of variable-length 
fields. These fields are illustrated in 
Figure 125 and are described in this 
section. 
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Relative 
Location 



72 

76 

80 
84 



92 

94 

96 
400 
404 
408 
412 
416 
420 
422 
423 
424 
428 
432 
436 
440 
444 
452 
453 
472 
476 
480 
484 
489 
492 
Figure 125, 



Field 



SAVE AREA 



SWITCH 



TALLY 



SORT SAVE 



ENTRY SAVE 



SORT CORE SIZE 



RET CODE 



SORT RET 



WORKING CELLS 



SORT FILE SIZE 



SORT MODE SIZE 



PGT-VN TABLE 



TGT-VN TABLE 



VCON PTR 



LENGTH OF VN TBL 



LABEL RET 



CURRENT PRIORITY 



DBG R14SAVE 



ANSC 



A(INITl) 



DEBUG TABLE PTR 



SUBCOM PTR 



SORT DDNAME 



SYSTDD 



Unused 



DBG R11SAVE 



Unused 



PRB1 CELL PTR 



Unused 



TA LENGTH 



Unused 



Relative 
Location 

500 

beginning 
of 

variable- 
length 
portion 



Field 



OVERFLOW 



BL 



DECABDR 



TEMP STORAGE 



TEMP STORAGE- 2 



TEMP STORAGE- 3 



TEMP STORAGE- 4 



BLL 



VLC 



SBL 



IND 



SUBADR 



ONCTL 



PFMCTL 



PFMSAV 



VN 



SAVE AREA- 2 



SAVE AREA- 3 



XSASW 



XSA 



PARAM 



RPTSAV AREA 



CHECKPT CTR 



VCON TBL 



DEBUG TABLE 



Figure 125. 



Fields of the Task Global 
Table (Part 2 of 2) 



Fields of the Task Global 
Table (Part 1 of 2) 
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The lengths of the variable-length 
fields are determined by the requirements 
of the program (if not required, a 
particular field may not exist in the 
object program) . 



SAVE AREA 

the program's save area; used to 
provide standard subroutine linkage 
when this program is called (by the 
Operating System or by another 
program) and when this program calls 

1^4- H £ir- nrr»rrramc 



SWITCH 

a fullword switch, 
bits are used: 



Only the following 



Main or subprogram switch. 
Set by INIT2 if this is a 
main program. 



Used for SYMDMP. It is set 
to 1 if the symbolic debug 
option is in effect for the 
program. This bit is tested 
by the object-time COBOL 
library debugging control 
subroutine ILBODBGO. 



i^ fr\r T?T r\\J 
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if the flow trace option is 
in effect for the program. 
This bit is tested by the 
object-time COBOL library 
debugging control subroutine 
ILBODBGO. 



Bit Meaning 

Indicates a size error in 

series addition or 
subtraction. If a SIZE 
ERROR clause was included in 
the source statement, and a 
size error occurs before all 
data items in the series 
have been added or 
subtracted, this bit is set 
to 1. It is tested after 
the entire addition or 
subtraction is complete. If 
the value is 1, the 
instructions generated for 
the ON SIZE ERROR clause are 
executed. 

1 Used for TRACE* It is set to 

1 by the execution of a 
READY statement, and reset 
to by a RESET statement. 
If the program uses a TRACE 
statement, there are 
instructions to test this 
bit at the point of 
definition for every source 
program procedure-name (PN). 
If it is on, the DISPLAY 
subroutine (ILBODSPO) is 
called to print the card 
number of the procedure- 
name. (See "Appendix B: 
COBOL Library Subroutines" 
for a description of the 
DISPLAY subroutine. ) 



Used for STATE. It is set to 
1 if the statement number 
option is in effect for the 
program. This bit is tested 
by the object-time COBOL 
library debugging control 
subroutine ILBODBGO. 

Used for OPT. It is set to 1 
if optimization has been 
requested for the program or 
if the SYMDMP or STATE and 
OPT, or FLOW and OPT options 
have been specified. 

Used for IF MESSAGE or the 
OVERFLOW option of the 
STRING or UNSTRING verb. It 
is set to 1 when the MESSAGE 
condition being tested is 
true or if an overflow 
condition occurs in the 
execution of STRING or 
UNSTRING. It is tested by 
the generated code. 

Used for CALL, CANCEL, or a 
recursive CALL. It is set 
to 1 by the generated code 
for the CALL or CANCEL verb. 
It is tested by INIT2 to 
determine whether a 
recursive CALL condition 
exists. 



10-11 Unused 



Indicates program initiali- 
zation. Set to 1 by routine 
INIT3 to show that 
initialization has been 
performed. Tested by INIT3 
so that if the module is 
re-entered, INIT3 can per- 
form re-entry functions 
instead of initialization 
functions. 



12 Used for QUOTE IS APOST. It 

is set to 1 if the 
apostrophe is to be used to 
delineate literals and to be 
used in the generation of 
figurative constants. 

13 Used for SYMDMP. It is set to 

1 if when SYMDMP is 
requested the program 
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contains a floating-point 
item. 

14 Always set to 1. 

15 Indicates maximum length for a 

variabl e— length field. 
Before the execution of a 
Q-Routine # this bit is set 
to 1 if the VLC and SBL for 
the field are to be set to 
their maximum possible 
values, rather than a value 
depending on the current 
value of a data item. The 
maximum value is the value 
of X in the clause "OCCURS X 
TIMES DEPENDING ON. . . ". 

16 SRVBIT set on if ILBOLOM is 

link-edited with program. 

24-31 DECIMAL-POINT IS COMMA clause 
byte. If this clause was 
specified, the byte contains 
a comma in EBCDIC. If not, 
it contains a decimal point. 



TALLY 



a fullword used for source program 
references to the special register 
TALLY. 

SORT SAVE 

a fullword used during the execution 
of a SORT RETURN statement to contain 
the GN for the next sequential 
instruction following the RETURN. 

ENTRY SAVE 

a fullword used to save the entry 
point of the program during INIT2 and 
INIT3 execution. 

SORT CORE SIZE 

a fullword for the SORT- CORE- SIZE 
special register as used in the source 
program. 

RET CODE 

a halfword for the RETURN-CODE special 
register, which is used in the source 
program to provide a completion code 
on a STOP RUN, EXIT PROGRAM, or GOBACK 
statement, or to store the return code 
from a called program. It is the 
user' s responsibility to set this 
code. 

SORT RET 

a halfword used to contain the return 
code from a SORT operation. 

WORKING CELLS 

variable-length cells used by COBOL 
library subroutines called by the 
program. The total length of the 
field is 304 bytes. 



SORT FILE SIZE 

a fullword for the SORT-FILE-SIZE 
special register as used in the source 
program. 



SORT MODE SIZE 

a fullword for the SORT-MODE-SIZE 
special register as used in the source 
program. 



PGT-VN TBL 

a fullword pointer to that part of the 
VN field of the PGT containing VN's 
for independent segments. 

TGT-VN TBL 

a fullword pointer to that part of the 
VN field of the TGT containing VN' s 
for independent segments. 

VCON PTR 

pointer to the VCON TBL field of the 
TGT. This is required because the 
VCON TBL field is variably located, 
and the VCON PTR is fixed within the 
TGT. 

LENGTH OF IND VN TBL 

a halfword containing the length of 
that part of the VN field (the length 
is the same for both the TGT and PGT) 
containing VN' s for the independent 
segments. 

LABEL RET 

the LABEL-RETURN special register for 
nonstandard labels. If an error 
occurs in such a label, it is the 
user's responsibility to place a 
nonzero value into this 1-byte cell. 

CURRENT PRIORITY 

if the STATE compiler option is 
specified for a segmented program, the 
segmentation subroutine ILBOS3M0 
inserts the priority of the segment 
currently in the transient area. This 
field is initialized to zero. 

DBG R14SAVE 

indicates the contents of register 14. 
A routine of the debug control 
subroutine ILBODBG0 is called to save 
this information before the execution 
of any instruction that passes control 
outside the COBOL program. 

ANSC 

identifies the object program as an 
American National Standard COBOL 
program. 

INIT1 ADCON 

address of INITl used for GOBACK, STOP 
RUN, and EXIT PROGRAM instructions, 
and for segmentation coding. 
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TGTTAB PTR 

if the FLOW SYMDMP or STATE compiler 
options are specified, this field 
points to the TGTTAB. 



SUBCOM PTR 

a pointer to the subroutine 
communications (SUBCOM) area in the 
COBOL subroutine library. 



SORT DDNAME 
an eicji 

SORT-MESSAGE special register, which 
is used in the source program to allow 
the user to specify to the Sort/Merge 
program where to place the messages it 
issues. 

SYSTDD 

DBG R11SAVE 

indicates the contents of register 11. 
When the dynamic dumping routine of 
the debug control subroutine ILBODBGO 
receives control, it places the return 
address to the in-line code of the 
calling program in register 11. 
Therefore, the contents of register 11 
must be saved. 

PRBL1 CELL PTR 

a fullword cell containing the address 
of the first PROCEDURE BLOCK cell in 
the PGT. 

TA LENGTH 

a halfword initialized to the length 
of the largest segment with a nonzero 
priority* 

OVERFLOW 

if the TGT is longer than 4096 bytes, 
this field contains one fullword cell 
pointing to each 4 096-byte area after 
the first. The cell is loaded into a 
register when a base is reguired for 
the overflow area. 

BL 

base locators. Each BL cell is a 
fullword containing an address in the 
data area. There is one BL pointing 
to the beginning of the Working- 
Storage Section and one for each file 
in the File Section. More than one BL 
is assigned if an area is larger than 
4096 bytes. 

DECBADR 

DECB addresses. There is one fullword 
cell pointing to the address of the 
DECB for each basic file. 

TEMP STORAGE 

temporary storage for arithmetic 
operations. TS space is allocated in 
doubleword blocks. 



TEMP STORAGE- 2 

temporary storage for nonarithmetic 
instructions. These cells are 
variable in length. 

TEMP STORAGE- 3 

temporary storage used to align fields 
of data described by the SYNCHRONIZED 
option. The field begins on a 
doubleword boundary. 

TEMP STORAGE- 4 

temporary storage cells used for trie 

Oijfirvv^n ri.Lj.Lj L.auj.c _ uauax j_ny vcljj. j.hc 

field starts on a doubleword boundary. 



BLI 



VLC 



SBI 



base locators for the Linkage Section. 
Each BLL cell is a fullword containing 
the address of an area passed as a 
result of an ENTRY statement, a label 
record, a totaled area, a sort 
description entry, or a GIVING option 
in a USE. . . ERROR statement. 



variable-length cells. Each VLC is a 
halfword whose value is set by the 
execution of a Q-Routine. It contains 
the current length of a variable- 
lengtn field. There is one VLC for 
each OCCURS. .. DEPENDING ON clause and 
all items to which it is subordinate. 



secondary base locators. Each SBL 
cell is a fullword set by the 
execution of a Q-Routine. It contains 
the current address of a field which 
is variably located because it follows 
a variable-length field. 



IND 



fullword cells, each containing the 
current value of an INDEX-NAME. There 
is one IND cell for each INDEX-NAME 
defined in a file. 

SUBADR 

subscript addresses. Each SUBADR cell 
is a fullword containing the address 
for a subscripted reference. 

ONCTL 

control counters for ON statements. 

-rp — _, u 4 -. — r..i l J ^„jj_^-.n^ r .^j j_^ 
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zero. 

PFMCTL 

PERFORM control counters and DEBUG 
saved location. Each PFMCTL cell is a 
fullword used for a PERFORM n TIMES 
statement to count the number of times 
the procedure has been performed. For 
DEBUG, a PFMCTL cell is used to save 
the contents of register 14 when the 
DEBUG packet is entered. DEBUG 
packets are called by BALR 14, 15. 
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PFMSAV 

PERFORM saved locations. Each is a 
fullword used to contain an address. 
For PERFORM, the cell is used to store 
the address of the next sequential 
instruction after the performed 
procedure, when that procedure is 
being executed because of a PERFORM. 
This is to enable the procedure to be 
executed in-line. 

VN 

variable procedure-names. Each VN 
cell is a fullword containing the 
current address of a branch point 
which may change during program 
execution because of an ALTER or 
PERFORM statement. 

SAVE AREA- 2 

pointer to the save area provided for 
label- and error-processing 
declaratives. 

SAVE AREA- 3 

variable number of fullwords used for 
OPEN parameters. 



XSASW 



XSA 



1-byte EXHIBIT switches. These are 
used as first-time switches for the 
coding generated for the EXHIBIT 
CHANGED statement. They are also used 
in certain types of SORT statements 
and ON statements. 



EXHIBIT saved area cells. These are 
variable in length and are referred to 
in the coding generated for an EXHIBIT 
CHANGED statement. There is one XSA 
for each operand to be exhibited with 
a CHANGED option. These cells are 
also used for SORT and RELEASE verbs. 

PAR AM 

parameter area of fullwords, 
containing parameter lists for macro 
instruction expansions of certain 
source statements. The size of the 
parameter area equals the largest 
number of words required for any one 
expansion. 

RPTSAV 

six words used to save branch 
addresses during the execution of 
Report Writer routines, if the Report 
Writer is used. 

CHECKPT CTR 

fullword cells used to count the 
number of file records processed for a 
file for which checkpoints are to be 
taken. 

VCON TBL 

8-byte V-type address constants for 



nonresident segments. The format of 
each entry is: 

By_t§ Q°.Qt.ents 

Priority number 

1-3 

4-7 VCON to independent segment 

DEBUG TABLE 

table used by the flow trace and 
statement number and symbolic debug 
COBOL library subroutines. The format 
depends on the options specified. 

• If the FLOW compiler option is 
specified: 

§Ztelsl Contents 

Number of traces requested 

1-3 Unused 

• If the STATE option is specified: 

IZt^I^). Contents 

0-3 Start of Q-Routines, or if 

none, start of INIT2. 
4-7 Size of Declaratives (not 

including Report Writer) 

Section. 
8-11 Starting address of PROCTAB 

in object module. 
12-15 Starting address of SE3INDX 

in object module. 
16-19 Ending address of SEGIt«DX 

in object module. 

• If both the FLOW and STATE compiler 
options are specified: 

B yte(s ) Contents 

Number of traces requested 
1-19 The same as shown above for 
the STATE option. 

• If the SYMDMP option is specified: 

Byte(s) Contents 

0-3 Start of Q-Routines, or if 

none, start of INIT2. 
4-5 Hashed compilation indicator. 

• If both the SYMDMP and FLOW options 
are specified: 

Byte(s) Contents 

Number of traces requested. 
1-5 The same as shown above for 
the SYMDMP option. 



PROGRAM GLOBAL TABLE 



The Program Global Table (PGT) contains 
data referenced by procedure instructions. 
All the fields in the PGT are variable in 
length. PGT data is never modified by 
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procedure instructions; rather, it remains 
constant throughout program execution. 

The fields in the PGT are illustrated in 
Figure 126 and described in the text below. 



DEBUG LINKAGE AREA. 



OVERFLOW 
VIRTUAL 



VIRTUAL EBCDIC NAMES 



PN 
GN 



DCBADR 
VNI 



LITERAL 



DISPLAY LITERAL 
PROCEDURE BLOCK 



Figure 126. Fields of the Program Global 
Table 



VIRTUAL EBCDIC NAMES 

indicates the EBCDIC names of library 
subroutines and user subprograms. If 
either the DYNAM or the RESIDENT 
option is in effect, the EBCDIC names 
of all Horary subroutines that are to 
be dynamically loaded are listed; in 
addition, if DYNAM is in effect, the 
EBCDIC names of all user subprograms 
that are to be dynamically called are 
listed. Each VIRTUAL EBCDIC NAME cell 
is a doubleword containing the name of 
the subroutine or subprogram, left 
justified and padded with blanks if 
necessary. If neither DYNAM nor 
RESIDENT is in effect, this field does 
not exist. 



PN 



source program procedure-names. When 
the OPT option is in effect, only 
those PN' s associated with ALTER and 
declaratives references receive PN 
cells. Each PN cell is a fullword 
containing the address of the first 
instruction in a block of coding. The 
addresses of the PN' s are in the same 
order as their definition in the 
source program. The program branches 
by loading an address from the PGT and 
then branching to it. 



DEBUG LINKAGE AREA 

a 12-byte area that contains the GN 
linkage for dynamic dumps. If the 
SYMDMP option is not specified, this 
area does not exist. 



OVERFLOW 

if the entire PGT exceeds 4096 bytes 
in length, there is one fullword 
OVERFLOW cell pointing to each 
4096-byte section after the first. 
The cell is loaded into a register 
when a base is needed to refer to the 
section of the PGT. 

VIRTUAL 

each virtual is a fullword containing 
the address of an external procedure 
(the result of an ESD and RLD in the 
object module) unless either the DYNAM 
or the RESIDENT option is in effect. 
If either of these options is in 
effect, the virtuals corresponding to 
library subroutines are written as VNI 
EBCDIC'/ 00 00 00';/ in addition, if 
the DYNAM option is in effect, the 
virtuals corresponding to user 
subprograms contain the relative 
displacement of the subprogram name 
from the beginning of the PGT. It is 
required because of a CALL statement 
in the source program or a branch to a 
COBOL library object-time subroutine. 



compiler- generated procedure- names. 
When the OPT is in effect, only those 
GN's associated with AT END and 
INVALID KEY references receive 3N 
cells. Each GN is a fullword 
containing the address of the first 
instruction in a block of coding. 
GN's are used in the same way as PN' s. 
They were generated to provide 
addresses for branches implied but not 
stated in the source program. They 
are stored in the PGT in the order in 
which they were generated. 



DCBADR 

DCB addresses. Each DCBADR cell is a 
fullword containing the address of a 
data control block in the data area of 
the program. There is one DCBADR cell 
for each DCB generated. 



variable procedure-name initialization 
cells. There is one fullword VN cell 
for each variable procedure-name in 
the program. It contains the initial 
value of the VN, and is used to 
initialize the VN values in the TGT. 
VN's are generated to contain branch 
addresses which vary because of 
PERFORM or ALTER statements. 



Appendix J: Fields of the Global Table 439 



LITERAL eliminated. each cell is a fullword 

literals referred to by procedure containing the address of a procedure 

instructions. The literals are block. The compiler assigns these 

variable in length. There is no cells only when the OPT option is in 

duplication in storage, since effect, 
duplicate literals were eliminated. 

PROCEDURE BLOCK 

DISPLAY LITERAL each cell is a fullword containing the 

literals used by calling sequences address of a procedure block. The 

rather than instructions. They are compiler assigns these ceils only when 

variable in length; duplication was the OPTIMIZE option is in effect. 
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(Where more than one page reference is given, the major reference appears first. ) 



S pec ia l Character S ubjects 

SSname subparameter 50,47,122 
*.ddname subparameter 50,47,122 
♦ iTOcsten subparameter 50 ? 47,122 
♦.stepname subparameter 50,47,122 
/♦statement 

description 18,61 

under MVT 292 
//* 61,49,20,21 

A, as a device class 18, 27, 58 
ABDUMP (see dumps) 
abnormal termination 
causes 190-196 
for COBOL files 134-137 
completion code 193-196 
COND parameter 32-34 
dump 

of data sets 60 

definition 190 

example 199-201 

finding records in 202—214 

how to use 196-202 

including problem program storage 
area 60 

including system nucleus 60 

requesting 70 

using 190 

with spanned records 204-205 
errors causing 191-195 
EVEN subparameter 35-36 
incomplete 204-205 
INVALID KEY clause 135-137 
ONLY subparameter 35-36 

restarting a job 26-28 

restarting a job step 42-43 

resubmitting a job 26 

size errors causing 420 

USE AFTER ERROR declarative 135-137 
ABSTR subparameter 
description 52 
in QISAM 114, 426 
ACCEPT statement, relationship to SYSIN DD 

statement 70 
ACCEPT subroutine 39 5—396 
accessinq 

a direct file 

randomly 87-88,89 

sequentially 87,89 
an indexed file 

randomly 119-121 

sequentially 113-119 
Queue structures 

queue Analyzer routine 248,249 

RECEIVE statement 248,249 

sample message retrieval options 24* 

SYMBOLIC QUEUE field 248 



a relative file 

randomly 100,102-103 
sequentially 102 

a standard sequential file 74-79 
accounting information 

EXEC statement 32,17 

JOB statement 24,17 
ACCT parameter 24 
actual key 73, 83-84 

(see also ACTUAL KEY clause) 
ACTUAL KEY clause 

(see also actual key) 

in BDAM 73,81-84,86-90 

in BSAM 73,81,84-85,87 

in file processing techniques 411, 412 

randomizing techniques 90-95 

division/remainder method 91-95 
indirect addressing 90-91 
synonym overflow 90-91 
ADCON table 420 
address constant table 420 
AFF parameter 51,47 
ALIAS statement 266 
al l oca ting mass stora ge space 
" ""SPACE parameter 57, 53 

SPLIT parameter 54 

SUBALLOC parameter 54 
allocation messages 173,175,182-184 
ALX subparameter 53 
APOST option 36 

APPLY CORE-INDEX clause 220,121 
APPLY RECORD- OVERFLOW clause 220 
APPLY WRITE-ONLY clause 148,150,220 
arguments 

data-name passed as 257-259 

file-name passed as 257, 258 

procedure-name passed as 257,258 
arithmetic subroutines 395-397 
ASCII file 

block prefix 80,79 

creating 7 9 

description 79-81 

error processing 81 

label processing 8 0, 143 

numeric data items 81 

opened as input 80 

opened as output 8 

sort for 307-308 
assembler language 

programs, linkage to 257-259, 270 

using EXEC statement 34 
ASSIGN clause 

for ASCII file 79 

in BDAM 72,96, 108 

in BSAM 72,108, 96 

in QSAM 7 5 

relationship to DD statement 72 

in Sort feature 302 
assigning values to index names 241-244 
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ATTACH macro instruction 418 
automatic call library 283,68 
automatic restart 

(see also Checkpoint/Restart) 

at beginning of job step 
EXEC statement 4 0-43 
JOB statement 25-26 

within a job step 329-330 
automatic volume switching 88-89 
average record-length subparameter 

for SPACE 52 

for SPLIT 54 



B, as a device class 18, 59 
base and displacement 176 
BASIS card 

in a debug packet 19 

use of 283-286, 430 
batch compilation 62-63 
BATCH option 62,39,41 
BCD 138-139 
BDAM 

data sets 124 

DD statement parameters 

defining a data set in 7 

definition 73 

direct organization 83,8 

error processing for 137 

relative organization 10 

permissible COBOL clauses 

programming techniques 2 

with spanned records 175 
beginning address of a file 
beginning address of a word 
binary 

(see also computational f 

intermediate results 231 

search of a table 244-24 

subroutines 396-397 
BISAM 

(see also QISAM) 

considerations when using 

data sets 124 

defining a data set in 7 

definition 73,74 

error processing for 135 

processing with 117-121, 
BLKSIZE 

with data sets 69-70 

in file processing 
techniques 76-79,410-41 

in QSAM 115 
BLOCK CONTAINS clause 52 

description 52 

in QSAH 75 
block length (see BLKSIZE) 
block prefix 80 
block size 

causing errors 193 

description 52 

for utility data sets 41 
blocked records 

fixed-length 144 

spanned 149 

variable length 145-148 



99,109 
4 

5,86-90, 116 

-139,423 

0-101,102-103 

108, 98 
20-221 
-176,216 

53 

53 

ields) 

-232 

6 



119-121,110 



-137, 424 
110,124 



3, 416 



6, 417 



BSAM 

data sets 123-124 

DD statement parameters 99, 109 

defining a data set in 74 

definition 73,74,84-85 

with direct file 73,74,84-83,87,89 

error processing for 132-137, 423 

permissible COBOL clauses 98,108 

with relative file 100-101,102 

subroutine 396-397 

user label totaling 140, 77 

with spanned records 184-185,216 

BUF option 35,36,41,417 

buffer offset 79 

buffer unit 359 

buffers 

allocating space to 416, 417 
specifying number 

for indexed files 114 
for standard sequential files 77 
truncating 220 

BUFNO subparameter 74-78,114,416,417 

BUFOFF subparameter 8 



C (conditional severity level) 178, 32, 33 
CALL 

option 41 

statement 252,253 
CALL statement 

and CANCEL statement 232 

definition 232 

dynamic 232 

dynamic loading 232 

and subprograms 232 
called programs 

additional input 272, 280 

identifiers 257,270 

input 

additional 272, 273, 280 
primary 265,68,280 

linkage 252-259 

primary input 265, b8, 280 
calling programs 

additional input 272,273,280 

identifiers 257-258, 265 

input 

additional 272, 273, 280 
primary 265,68,280 

linkage 252-257,258 

primary input 265, 68, 280 
CANCEL statement 

and subprograms 232 
capacity records 83-84, 87 
CATALG subparameter 5 9 
catalog, system 15 
cataloged data sets 

creating 125 

description 132 

retrieving 128 

on a volume 137 
cataloged procedure 

adding to the procedure library 28 9 

bypassing steps within 32 

calling 289 

COBUC 291,292,293 

COBUCG 291,2 94 
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COBUCL 291,292,293 

COBUCLG 291,294,295 

COBULG 291,293,294 

with COND parameter 25,32-34 

data sets produced by 289-290,292 

DD statements 4 9 

definition 18 

dispatching priority 41 

IBM-supplied 291-292 

limiting execution time of 44 

modifying 295-297 

naming 292 

overriding 295-297 

PROC statement 61 

programmer-written 290 

relationship to SYSl.PROCLIB 125 

required device class names for 50, 51 

restarting programs with 25,26,42-43 

return code 32-33 

using the DD statement 290-294 

using the EXEC 
statement 30,31,290,291,295-296 
CATLG parameter 128,132 
CD entries 222 
character delimiters 21 
checkid 26,329-330 
checklist for job control 

procedures 429-432 
Checkpoint 

(see also Checkpoint/Restart) 

CHKPT macro 
instruction 25,42-43,328,329 

eons iderat ions 32-6-32-9 

data set 26 

how taken 42-43,327 

initiating 327 

in a job 25-27 

in a job step 42-43 

messages 329 

multiple 327 

RERUlif clause 25-26,42-43,327-329 

restart 42-43,327-329 
(see also Restart) 

single 327 
Checkpoint/Restart 

checkpoint 327-333 

see also Checkpoint) 

data sets 331-333 

DD statements 327 

designing 328 

in a job 26-27 

in a job step 42-43 

messages 329 

methods 327 

RD parameter 

with checkpoint 329 

for a job 25-27 

in a job step 42-43 

restart 321-333 

(see also Restart) 

with Sort/Merge 30 6 

subroutine 399 

SYSCHK DD statement 330-331 
CHKPT macro 

instruction 25-27,42-43,328-329 
CLASS parameter 27,23 
class test subroutine 4 02 
classname subparameter 59 



CLIST option 3b, 41 
CLOSE REEL statement 7b 
CLOSE statement 

BSAM subroutine 3 96 

creating multi volume files 

with direct organization 88-89 
with relative organization 102 

efficient use 231-232 

with error processing 135, 136, 137 
CLOSE UNIT statement 84,88,89,102 
COBOL copy library 

COBOL sequence numbers 28 5 

entering source statements 283, 284 

IEBUPDTE sequence numbers 28 5 

retrieving source statements 
BASIS card 285, 286, 33 
COPY statement 284,285,33 

updating source statements 284 
COBOL file processing (see file, process inq 

techniques) 
COBOL library subroutines 282,395-399 

concatenating 287 

sharing 287 
(see also library) 
COBOL RERUN clause 25,26,42-43,327-329 
COBOL sample program 383-394 
COBOL sequence numbers 285-286,36 
COBOL subroutine library 281, 414-418 

(see also library) 
COBUC 291, 292, 293 
COBUCG 291,294 
COBUCL 291,292,293 
COBUCLG 291,294^295 
COBULG 291,293,294 
CODE clause 2 39 
command statement 61,17 
comments 

continuing 21 

field 20,21 

statement 61,17 
communication with other languages 2 59 
Communications Description (CD) 
entries 222 

and Communications Section 222 

format 222 

and Teleprocessing 222 
Communication Section 222 

and Communication Description (CD) 
entries 222 

and Message Control Program 222 

and Teleprocessing 222 
compare subroutine 3 98 
compilation 

(see also compiler) 

batch 62-63 

cataloged procedure 289,290 

checklist for job control 
procedures 429,430 

data set requirements 6 4-66 

definition of 15 

example of job control 
statements 429,430 

invoking compiler at execution time 418 

sample program 383-394 

source program size assuming minimum 
configuration 420 

syntax checking 187 

using the REGION parameter 379 
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compiler 

(see also compilation) 

blocking factor for data sets 41b 

buffer space 416,417 

calling 418,419 

capacity 420,421 

data set requirements 64-66 

internal name 175 

invoking 416,418 

machine requirements 379 

optimization 416, 417 

options 35-43 

output 

allocation messages 175 

cross-reference dictionary 177 

diagnostic messages 179 

global table 176-177 

glossary 175-176 

job control statements 175 

object code 177 

object module 179 

sample output 173-175 

source module 179,175 

PARM option 35-41 

segmentation output 312 

specifying in EXEC statement 30 
completion codes 

description 193-196 

in Sort program 30 5, 306 
computational fields 

conversions involving 22b-228 

conversion subroutines 394-399 

description 228,229 
COMPUTE statement 232-233 
COND parameter 

EVEN, ONLY subparameter 34,35 

in cataloged procedures 295-296 

in EXEC statement 32-34 

in JOB statement 25,23 
condensed listing, using CLIST 36 
conditional, as a severity level 

(C) 178,32 
conditions terminating execution 25, 32-34 
configuration section 220 
CONTIG subparameter 

description 53 

with direct files 89 

with indexed files 114 
continuation of job control statements 21 
control cards, SYMDMP 158-lbO 

example of 159 

line 159-160 

object-time 158-159 

placement of 159 

prognam 159 
control program 15 
control statements 

character delimiters 21 

command statement 61,17 

comment statement 61, 17 

continuing 21 

DD statement 46-60,17 

delimiter statement 61,17 

EXEC statement 29-45,17 

fields 20 

JOB statement 23-29,17 

notation used for 22 

null statement 61, 17 



preparing 20,21 

PROC statement 61,17 

processing 19 

use 17 
control transfer isee calling programs and 

called programs) 
conversion subroutines 395-399 
copy library (see COBOL copy library) 
COPY statement 

DD statement requirements 430 

use 284,286,33 
core storage (see main storage) 
creating a file 

direct 67,70,83-87,124,88,89 

indexed 113-116,124,427-429 

relative 73-76,101-103,124 

standard sequential 64-67,121-124 
cross reference 

dictionary 177,36,38 

list 

description 181,182 
used in dumps 198-202 
CYL subparameter 

for SPACE 

consideration for indexed files 114 
description 52 

for SPLIT 53 
cylinder overflow area 110-112 



D (disaster severity level) 178, 32-33 
data alignment 227-230 
data areas, locating in 

a TCAM program 216-217 
data control block 

(see also DCB parameter) 

description 133,134 

fields 409-414 

identifying 134 

overriding fields 134 
data conversion 226-228 
data definition 46-60,17 

(see also DD statement) 
data description 222-230 
Data Division, programming 

techniques 221-230 
Data Division dump (with SYMDMP* 

and FD 158 

and index- name 158 

and RD 158 

and SD 158 
data extent block 63-64 
data formats 228-230 
DATA parameter 

in DD statement 49,47 

restriction with UNIT parameter 51 
data set control block 138, 50-59 
data set labels 

description 134-143 

relationship to DD statement 134 

specification of 74 
data set member 73 
data sets 

adding records to 58 

(see also MOD subparameter) 

allocating space for 52-53 

blocked 69 
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cataloging 

description 59, 132 

indexed files 117 
checkpoint 327-329 
concatenating 297-298 
creating 121-127 
definition 15 
deletion of 58,132 
delimiting in input stream 61 
describing attributes of 47 
direct 73,84-89,124 
disposition of 

after abnormal termination 216-219 

description 57, 59 
errors involving 191-194 
execution time 6 8-70 
extending 129 

generation data groups 132,133 
identifying 

description 50 

for compilation or linkage 
editing 49 
in the input stream 49,64,129,132 
in the output stream 59-60,63-65,124 
indexed 109-113,119-121 
intermediate, under MVT 380-381 
labels 57,137-142 
magnetic tape 122-124 
names 

description 133 

relationship to file names 72 

nqnt empor ary 5 4 

organization 73 
partitioned 281-288 
postponing definition of 49,50 
produced by cataloged 

procedures 289-294 
relative 73,100-107 
retaining 58-59 
requirements 

for compilation 58-65 

for execution 6 8-70 

for linkage editing 66-68 

for loading 68-69 
retrieving 128-131 
scratching 218-219 
sharing 58 

standard sequential 73-81 
system catalog of 15 
temporary 54, 55 
unit record 122-123 
used by Checkpoint/Restart 327-329 
used by Sort 302-304 
DATE- COMPILED paragraph 175 
date subroutine 3 99 
DCB macro instruction 4 09 
DCB parameter 

(see also data control block) 
for defining checkpoint data 

sets 327-329 
description 133-134 
error processing with 134,135,423 
identifying information in 134 
retrieving previously created data 

sets 128,129 
subparameters 

for direct files 

accessed randomly 412 



accessed sequentially 411, 99 
for indexed files 

accessed randomly 128-130,396 
accessed 
sequentially 113-117,413,414 
for relative files 

accessed randomly 412 
accessed sequentially 109, 411 
for standard sequential 
files 76-79, 410 
DD statement 

adding to a cataloged procedure 

description 17, 46 
error recovery option, for standard 

sequential files 135,136 
format 47, 48 
overriding in cataloged 

procedures 296-301 
parameters 46-60 
requirements for 

ASCII files 80,143 

compilation, job step 429, 430 

compiler data sets 61-66 

changing a Horary with 290 

direct files 99 

execution, job step 431, 432 

execution time data sets 129 

extending data sets 129 

indexed files 113-120,425-427 

job run in MVT environment 380-381 

linkage editing 

data sets 66-68 
job step "430, 431 "" 
loader data sets 68,69 
relative files 109 
retrieving data sets 128-131 
standard sequential files 76-81 
unit record devices 132 
using cataloged procedures 290-294 

£>ing v-udOu c^py norary zc^fZ^i-i 
using the Sort feature 302-305 
relationship to ACCEPT statement 70 
relationship to DISPLAY statement 69-70 
relationship to SELECT statement 134 
Sort feature, used in 302-305 
used to complete the DCB 133, 134 
DDNAME parameter 

in cataloged procedures 297-301 
ddname subparameter 50 

(see also ddname subparameter* 
description 47,49,50 
error message 

use of 47,49,297-301 
ddname subparameter 

and calling and called programs 30,31 
and cataloged procedures 29b-301 
checklist of use in JCL 

procedures 4 30,431 
with Checkpoint/Restart 327,329 
and creating files 123 
in DD statement format 47,48 
as DDNAME subparameter 50 

(see also DDNAME parameter) 
as DSNAME 

subparameter 50, 113, 114, 128, 129, 131 
in EXEC statement format 30 
as INCLUDE operand 271, 265 
and indexed files 113-118 



Index 445 



as LIBRARY operand 271,265 

in name field of DD 
statement 47-49, 72, 125-127, 296-301, 
327-329 

as PGM subparameter 30, 31 

and retrieving files 128-129,131 

as stepname qualifier 295-298 

as SU3ALLOC parameter 54 

and subprogram linkage 272, 273 

used to allocate space 54 

using with queue structures 249 
DEB 64 

DEBUG card 187 
debugging facilities 202-203 
debugging language 187-190 

(see also TRACE statement and EXHIBIT 
statement) 
debugging packed 189-190 

debugging a program (see program debugging* 
debugging, symbolic 157-172 

example 162-172 

FLOW 157 

STATE 157 

SYMDMP 158-157 
DECB 

error conditions 423,424 

linking with 252, 253 
decimal point alignment in PICTURE 

clause 223-225 
DECK option 35,36,41,429,179 
Declaratives, USE AFTER ERROR 

option 135-137 
DEFER subparameter 52 
deferred restart 330-331 
DELETE statement 127,285,286 
DELETE subparameter 

and cataloged data sets 132 

definition 58 
delimiter, Job Control Language 

character 21 
delimiter, job control statement 17, 61 
DEN subparameter 76 
DEPENDING ON option, programming 

techniques 241,242 
describing files 72-156 
determining file space 90, 92 
device allocation 175 
device class 

blocking restrictions 51-52 

and compiler data sets 61-65 

definition 15 

examples of names 18 

and execution time data sets 6 9 

and linkage editing data sets 67, 68 

and UNIT parameter 51, 52 
diagnostic messages 

compilation 177,178,173 

linkage editing 183,179 

with ON statement 187 
dictionary, cross-reference 177 
direct access (see mass storage) 
direct data sets 

creating 124,84-86 

description 81-83 
direct file 

creating 84-89,124 
randomly 8 6-87,89 
sequentially 84-85 



description 81-84, 89 

error processing 135 

multivolume 88-89 

randomizing technique 95 

reading 

randomly 87-88 
se<ruentiallv 87 , 8 9 

sample program 96-97 
Direct SYSOUT Writer 124 

directory-quantity JCL subparameter 52, 53 
disaster, as a severity level 

(D) 178, 32, 33 
disk (see mass storage) 
DISP parameter 

data set uses 

cataloging 132 
creating 122-124 
retrieving 128-132 

default values of 59 

description 58-59 

in JOBLIB DD statement 60 

in Sort feature 303-305 

subparameters 58,59 
displacement and base 176 
DISPLAY option of USAGE clause 

and comparisons and moves 228,229 

and data format conversion 226. 228 

external decimal format 229 
DISPLAY statement 

and COBOL output files 7 2 

conversions involving 228-229 

relationship to DD statement 69-70 

use of 186 
DISPLAY subroutine 396-397 
disposition messages from joo 

scheduler 183-185 
division/remainder method for 

randomizing 91 
DMAP compiler option 36,35,41,175 
DPRTY parameter 4 3-44 
DSNAME parameter 

definition 50 

and file creation 121 

and file processing techniques 
direct 99 

indexed 113,118,116 
relative 109 
standard sequential 78,79 

format of 47, 4 8 

and single-volume files lls-117 

subparameters 50 
DSORG 

direct files 99 

indexed files 116,119 

relative files 109 
DUMMY parameter 

definition 50 

format 47 
dummy records 

in direct files 83,84,85 

in relative files 102,103,104 
dumps 

completion codes 191, 193-196 

DD statements to request 60,70 

definition 60 

determining location of error 196-19P 

dynamic 190-191 

and compile-time option 190 
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SYMDMP 191 
locating records in 20 2-214 
locating working storage in 221,222 
reguesting 

using SYSABEND DD statement 70,60 

using SYSUDUMP DD statement 70, 60 
and symbolic debugging 157 
types of 

abnormal termination 190-191 

indicative 191 
use of 191,192 
DYNAM option 267 
dynamic subprogram linkage 253 
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DYNAM option 254 
example 254,255,256 
NOYDNAM 254 



E (error severity level) 178,32,33 

EBCDIC 77,138,191 

efficient programming (see programming 

techniques) 
entry name 264 
entry-point 

of called programs 264 
of loaded programs 40-42 
Environment Division, programming 

techniques 220,221 
environments, operating system 16 
EP option 41, 42 
EROPT~subp"a"rameter "134, 135,4X0 
error 

completion codes with 27, 191-196 
conditions 

input/output 191-19 6 
invalid data 191-192 
messages 

condition code 32, 3 3 
compile time 177-178,186 
linkage editor 183 
loader 18 3 

object time 284-285,186 
system 186,178,33 
severity codes 178, 32-33 
recovery 

COBOL ERROR declarative 135-137 
DD statement option 134,135,410 
direct file 137 
indexed file 135-137 
relative file 137 
standard sequential file 135 
system 134,135,137 
table 136 
as a severity level (E) 178, 33, 32 
ESD (see external symbol dictionary) 
establishing a priority 
for a job (PRTY) 28 
for a job step 

(DPRTY) 43-44 
EVEN subparameter 33-34 
EXEC statement 

accounting information (ACCT) 32 
additional storage (ROLL) 45-46 
bypass/execution conditons (COND) 32-34 
compiler options of PARM 
parameters 35-42 



definition 16 

dispatching priority (DPKTY; 43-44 

identifying 

procedure (PROC) 30-32 
program (PGM) 30-31 
step (stepname) 30-32 

linkage editing options of PARM 
parameter 35-42 

loader options of PARM parameter 37-42 

PARM parameter 35-42 

passing information between 
programs 41-42 

setting time limit (TIME) 43-44 

specifying region size < REGION) 44-4 5 

requesting restart (RD) 42-43 
execution time 

data sets 68-70 

definition 16 

job control checklist 431,432 

options 42-44 

output example 185,283-394 

storage allocation 381, 382 

with REGION parameter 379 
EXHIBIT statement 

and program debigging 188,189 

and required DD statement 70 
EXHIBIT subroutine 3 96-397 
exit list codes 141-142 
EXPDT subparameter 58 
external decimal subroutines 330, 331 
external floating-point subroutine 39b 
external name 364 
external reference 36 4 
external symbol dictionary (ESD) 180 
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file 
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clauses 73, 75, 98, 108, 117-121, 220-221 
and DD 

statement 73, 7o-81, 99, 109, 113-116 
definition 72 
name 73,89-90 

processing techniques 72-122 
ASCII 80 
direct 81-99,73 
indexed 73,108-130 
partitioned 73, 281, 289 
relative 73,100-107 
standard sequential 73-78 
and SELECT sentence 73 
space allocation 

for 52-56,73,114-117,84,85,86 
user defined 73-142 
file-name 

argument in calling program 264 
definition 72 
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techniques 221,222 
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FLAGE option 37,41 
FLAGW option 37 # 41 
floating-point 

subroutines 396,397 
floating-point data items 
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intermediate results 231-232 
FLOW option 202-203,157 

and HUM 157 
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generation data set 132,133,50 
GIVING option of Sort feature 302 
global table 
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MAP option 
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description 175, 176 

reguesting through EXEC statement 36, 41 
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causing errors 193 
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system storage 28-29 
holding a job 29 



I/O (see input/output) 
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considerations 382 
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IEBUPDTE subroutine 283,284 
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IF statement 

and Teleprocessing applications 232-233 
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technigues 231-232 
IKFCBL00 routine 272 
ILB subroutines 395-399 
INCLUDE statement 271-272,265,288 
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independent overflow area 111,112,113 
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data item 241 
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master 117 
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assigning values to 242 
overflow area 111,112,113 
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description 109-124 

error subroutine 396-398 
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random access 119 

RECORD KEY clause 110 
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seguential access 117,118,119 

updating 117,120 
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files) 
indexing a table 242-246 
indicative dump 

description 191 

restriction for MVT 193 
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informative messages 175,178,181-183 
input/output 
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device allocation 51, 52 

error conditions 

completion codes for 193-19b 
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standard error 135-137 

summary of 423, 424 
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statement 45-59 

subroutines 395-398 
input stream 
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INSERT statement 2 85 
in-stream procedures 61, 31 
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interrupt 19 3,194 
intermediate results 231-232 
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invalid key error conditions 135-137 
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holding for later execution 29 

identifying 23 

library 28b-288 
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request for restart 25-26 
setting time limits 27 
storage specification 28-29 
terminating 25 
Job Control Language 
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coding 19-22 
examples of 

compilation 173 

linkage editing 181 
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comments 21 

name 20 



operation 20 
notation 22 

statement continuation 21 
types of statements 

command statement 61, 17 

comment statement 61,17 

DD statement 45-60, 17 

delimiter statement 61, 17 

EXEC statement 29-45,17 

JOB statement 23-29,17 

null statement 61, 17 

PROC statement 61, 17 
job control procedures 17-70,429-432 
cataloged procedures 289-301 
checklist for 429-432 
Checkpoint/Restart 18 9-333 
definition 17 
libraries 281,283,284-288 
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sort 302-305 

for user files (see file, processing 
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-job management routines 19 
job schedulers 

description 19, 21 

disposition messages from 183—185 
JOB statement 23-29 
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definition 23 
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parameters 
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COND 25 

MSGCLASS 2 8 

MSGLEVEL 24-25 

PRTY 28 

RD 26-27 

REGION 28-29 

RESTART 26-27 

ROLL 29 

TIME 27 
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job step 
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using EXEC statement 32-34 
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dispatching priority 43-44 

restarting 42-43 
JOBLIB DD statement 
description 60 
example of use 431 
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parameter 299,300 
jobnarne 23 
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standard 137-138,139 

standard user 13 9 

user 138-143 
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LET option 41, 42 
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library 

automatic call 68,283 

changing 288 

COBOL copy 283 

COBOL subroutine 282, 395, 399 

compilation, use of 65-66 

concatenating 60, 65, 28 6 

copy 283 

creating 288 

directory 281 

job 286 

link 281-282,67 

partitioned data set 73 

for PGM parameter 30-31 

private 30, 60 

procedure 30,282 

for program checkout 190 

relationship to JOBLIB DD 
statement 60,68 

relationship to SYSLIB DD 
statement 65, 66 

sort 282 

source program 2c 3 

subroutines 

arithmetic 395, 396 
COBOL 282 
conversion 395, 396 
input/output 3 95,396 
intermediate results 231-232 

system 30 

temporary 30 

user 282-283,60 
LIBRARY statement 271, 265 
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line control cards 159-16 

format 159 

line-num 159 

verb-num 159 
link library 281-282, 67 
LINK macro instruction 280,118 
linkage conventions 252—258 
linkage, dynamic subprogram 

(see dynamic subprogram linkage) 
linkage editor 

additional input 265, 272 

calling compiled programs 419 

capacity 421-422 

checklist 430 

data set reguirements 66-68 

definition 16 

external names 264 

input 

additional 265, 272 
primary 265,272 

with libraries 286-288 

LIBRARY control statement 283 

messages 185 

options 40,41,42 

output 179-183 

PARM options 41,42 

with preplanned overlay 273-275 

primary input 265, 272 

processing 264-273 

user-specified data sets 68 
linkage registers 257, 258 
LINKLIB 67,281,282 
LIST option 40, 41 
literal pool 176 

literals, size considerations 421 
LOAD macro instruction 418 
load module 

definition 15 

as input to linkage editor 265,272,273 

length of 20 2 

output 18 3 

specification in EXEC statement 3 
LCAD option 36,41,179 
loader 

cataloged procedure 294,295 

data set requirements 68, 280 

definition 280 

invoking 294,295 

input 

additional 280 
primary 68,69,280 
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module map 183,184,36,41 

output 183-184 

PARM options 35-41 
loading programs 
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cataloged procedure 294, 295 

primary output 68, 28 
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logical record length 64-65,410-414 
logical record size 

for SYSIN 415 

for SYSLIB 415 

for SYSPRINT 415 

for SYSPUNCH 415 
LRECL 64-65,410,414 
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ATTACH 418 
CHKPT 329,330 
DCB 298 
LINK 275, 417 
LOAD 417 
magnetic tape 
data sets 

sharing devices 304 
using DEN and TRTCH 
subparameters 76,77,78 
devices 

compiler optimization using 415 
labels 137,138-139 
in Sort feature 302,304,382 
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private 55, 56, 57 
removable 53-54 
reserved 55, 56 
scratch 55, 56 
main line routines 230-231 
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(see also storage allocation ana storage 
considerations ) 
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hierarchy support 

hierarchy 28-29 
hierarchy 1 28-29 
REGION parameter 44-45,28-29 
requirements for Sort/Merge 260-261 
map 

loader storage 183, 184 
memory 174 
module 181-183 
MAP option 

for linkaae editor 40,41,182 
for loader 40,41,183-184 
mass storage 

device 90,92,93 
space allocation 

SPACE parameter 52-53 
SPLIT parameter 53-54 
SUBALLOC parameter 54 
volume labels 157 
volume status 54-5 6 
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master index 117 
master schedulers 19 
MCP 334 

MCP and communication between COBOL 
programs 370, 375 

activating the interface 375 
additional considerations 375-376 
defining the interface 370 
defining process control blocks 37o 
MCP macros 

CLOSE 359 
DCB 360 
INTRO 359 
INVLIST 361 
OPEN 359 
PCB 360 
READY 359 
RETURN 359 
TERMINAL 361 
TLIST 361 
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TTABLE 361 
message control program (MCP) 
activating 359 
building 

assembling 3 65 
executing 365-366 
link-editing 365 
data sets 360, 366-367 

checkpoint data sets 366 
group data sets 366 
message gueue 366-367 
defining buffers 3 59 
defining terminal area 360-362 
functions of 337 
message flow 334-336 
RECEIVE statement 234 
SEND statement 234 
user tasks 337 
writing a 337-338 
message handler (MCP) 359-365 

for application programs 364-3 65 
delimiter macros 362, 363 
functional macros 362, 363 
for terminal line groups 363 
messages 

allocation 

compiler 175 
linkage editor 182-183 
checkpoint 329, 333 
compiler, summary of 177,178 
disposition 

compiler 177 

linkage- editor-- -182 

error 32-33 

identification codes 186 
linkage editor 183,184 
object time 284-285 
operator 18 6 ^"""* 
severity level of 
compiler 32-33 
linkage editor 32-33 
sort 305, 307 
MFT (see multiprogramming with a fixed 

number of tasks) 
MOD subparameter 58 

in Checkpoint/Restart 328,329 
in compilation 65 
definition 58 
MODE subparameter 77 
modular levels 230-231 
module map 181-184 
MOVE statement 231-23 3 
MOVE subroutine 397-3 98 
MSGCLASS parameter 28-29,23 
MSGLEVEL parameter 
description 24—25 
on JOB card 23 
with restart 329-331 
multiple checkout 327 

multiple OPEN and CLOSE statements 381 
multiprogramming with a fixed number of 
tasks 

assigning job class 27 
data sets 

marking end of 61 
scratching 218-219 
sharing 64-65 
definition lb 



holding a job 29 
JOB statement parameters 27-29 
priority scheduler 19 
multiprogramming with a variable number of 
tasks 

assigning a job class 27 
bypassing I/O 49 
causing errors 193 
Checkpoint/Restart 327-333 
data sets 

intermediate 380 
marking end of 61 
scratching 218-219 
sharing 64-65 
definition 16 

EXEC statement parameters 43-46 
holding a job 29 
input stream in 4 9 
JOB statement parameters 23-29 
job step 

additional storage for 44-45 
dispatching priority 43-44 
time limits 43-44 
machine considerations 380 
main storage requirements 28-29, 44-4 5 
with multiple OPEN and CLOSE 

statements 380 
priority schedulers 19 
region code 16 

REGION parameter 28-29, 44-4r>, 379, 380 
Restart 26-27,42-43,329-333 
ROLL parameter 29,45-46 

.SPACE, parameter ..._ 186 _ 

multistep job 32-33 

multi volume data sets /" 

for direct files 88-89 
for relative file 102-103 
volume switching && 
MVT (see multiprogramming with a variable 

number of tasks) 
MXIG subparameter 53 
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NAME option 39, 41 
NAME statement 2 66 
name subparameter 51 
names 

cataloged procedure 50 

data set, conventions used in 133 

generation 50 

procedure 420,421 

qualification of 50, 421 

temporary 50 
NEW subparameter 58 
NL subparameter 58 
NOBATCH option 39, 41 
NOCALL option 42, 41 
NOCLIST option 36,41 
NODECK option 36,41 
NODMAP option 36,41 
NODYNAM option 268 
NOFLOW option 37,41 
NOLET Option 42, 41 
NOLIB option 39, 41 
NOLOAD option 36,41 
NOKAP option 40,41 
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NOMINAL KEY 73 

NONAME option 39,41 

nonstandard labels 137,140-141 

NONUM option 38,41 

NOPMAP option 36,41 

NOPRINT option 39,41 

NORES option 42, 41 

NORES I DENT 268 

NOSEQ option 36,41 

NOSOURCE option 36,41 

NOSTATE option 37, 41 

NOSUPMAP option 37,41 

NOSXREF option 38,41 

NOTE statement 233 

NOTERM option 40,41 

NOTRUNC option 37,41 

NOXREF option 38,41 

NEL subparameter 58 

null statement 17, 61 

NUM option 38, 41 



object code listing 177 
OBJECT- COMPUTER paragraph 220 
object module 

contents 179 

deck 179 

definition 15 

dumps using 196-201 

listinq 179 

size considerations 421 
object-time control cards 

continuation cards lo9 

control statement placement 159 

example of 159 

line-control cards 159-lbO 

program-control cards 159 

syntax rules 158-159 
object time overlay 309 
OCCURS clause 

causing errors 192 

DEPENDING ON option 241-242 
OCCURS DEPENDING ON 

clause 241-242,395,154-156 
OLD suoparameter 58, b 7 
ON SIZE ERROR option 

binary items 232 

intermediate results 232 
ON statement 187,188 
ONLY subparameter 34 
OPEN statement 

multiple use of 381 

for several files 233 
operand field 

bypassing I/O 4 9 

on control statement 20 

data definition 4 9 
operating system environment 

multiprogramming with a fixed number of 
tasks 16 

multiprogramming with a variable numbc^r 
of tasks 16 
operation field 20 
operator 

commands 61 

messages 186 
OPTCD subparameter 77,410,411 



optimization, compiler 417, 418 

optional services (see OPTCD suoparameter) 

options 

for compilation 35-39,41 

for execution 42-4 4 

for linkage editing 40,41 

for loader 40, 41, 42 
output 

classes 27 

compiler 173-179 

definition 15 

displaying control statements 24 

linkage editor 179-186 

loader 183 

MAP option 4 0, 41 

requests for 186 

sample program 383-394 

storage on library 30 

stream data sets 124 

suppressing 415-416 

SYSOUT parameter 59-60 

system 186 
overflow 

area (see QISAM) 

index 111,112 

synonym 91,95 
overlay 

dynamic 275 

preplanned 273-274 

statement 273-274 

structures 273-274 
overriding DD statements 296-301 
OVFLOW 113, Hi, lib, 118 
OVLY option 40, 41 



page breaks, optimizing in Report 

Writer 238-239 
PARM option 

compiler options 35-42, 41 

with equal sign 3b 

job card 42-43 

linkage editor options 40, 41 

restrictions 35 

significant characters 35 
parameters 

compared to arguments 257-258 

keyword 20-21 " 

positional 20 

subparameter s 20 
partitioned data set 

description 73 

directory 281,53 

member 73,281 

primary quantity for 53-54 

secondary quantity for 53-54 

temporary libraries 30 
partitions 16 
PASS subparameter 59, 53-55 
PASSWORD subparameter o8 
PDS (see partitioned data set) 
PERFORM verb 233-234 

in a segmented program 311 
permanently resident volumes 5o-5b 
PGM 30 

PGT (see program global table) 
physical records, size restriction 53-o4 
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PICTURE clause 223-224 

efficient use of 223-224 
storage allocation 223-224 
PMAP option 36, 41 
prefixes 221-222 

preplanned linkage editor 273-274 
PRESRES, member of SYS1. PROCLIB 55-56 
primary input, for called and calling 

programs 264-265 
PRIME, in QISAM 113-114 
prime area (see QISAM) 
prime number list 94 
PRINT option 39,41 

printer, determining line spacing 77 
priority, assigning 
for a job 28 
for a job step 43-44 
priority schedulers 19 
priority scheduling system 
EXEC statement parameters 
JOB statement parameters 
relationship to multiprogramming 

environments 16 
sharing data sets 58-59 
SYSOUT parameter for 6 
PRIVATE subparameter 56 
private volume 55-56 
PROC statement 17,61,20 
Procedure Division 

intermediate results 
modular levels 230 
programming techniques 

— segment at ion - 3-10— 31 2 

verbs 232-235 
procedure library 18,282,289 
procedures, in-stream 61, 30 
processing programs 15 
processing subroutines 231 
procstep. ddname 4 9 
procstep subparameter 53, 54 
program 

see also programming techniques) 

called 252-255 

calling 252,419 

checkout 187-219 

debugging 

completion code 193-196 
dumps 190-191,196-198 
errors 

I/O 191 

invalid data 191-192 
other 193-198 
I/O errors 191 
incomplete abnormal 

termination 216-219 
invalid data errors 191-192 
language 187 
other errors 193-198 
execution 

multistep job 32 
from private library 30 
from system library 30 
from temporary library 30 
interrupt 196 
linkage editing 264 
sample 383-394 
selective testing of 189-190 
techniques (see programming techniques) 



program-control cards 
ddname 159 
format 159 
program- ID 159 

program global table 177 

PROGRAM- ID 

and FLOW option 157 
and STATE option 157 

programmer identification 24 

programming techniques 
(see also program) 
Data Division 221-230 
Environment Division 220 
general 220 

Procedure Division 230-246 
Report Writer 236-241 
Sort Feature 305 
Table Handling 236-246 

PRTSP subparameter 77 

PRTY parameter 28,23 

pseudo data set 4 9 

public volume 55, 56 
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Q routines 
QISAM 

considerations when using 117-120 

data control block 49,118-119 

data sets 

creating 110,113-117 
definition 73 
deleting records in 119 
reor-gani^ing— 118-119 _ 

DD statement paramaters 49,118-119 

error processing for 135-137, 423-424 

indexes, description 110,112 

master index 117 

overflow area, description 111,112,113 

prime area, description 112 

single volume file 118-119 
QSAM 

data control block 49,118,119 

data set 123,124,73 

DD statement parameters 113-116 

description 74-79 

error processing for 135, 423 

Sort feature, uses of 302 

user label totaling 14 

with spanned records 148-151, 216 
Queue Analyzer Routine 248,249 
queue blocks 

and locating TCAM data areas 216-217 

sample program 217 
QUEUE DEPTH field 233 

and IF statement 233 
Queue structure considerations 

accessing with COBOL 248-251 

example 246,247 

Queue Structure Description routine 251 

SYMBOLIC QUEUE name 24 6 
QUOTE option 36, 39 



randomizing techniques 90-91,95 
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with checkpoint 329-330 

for a job 25-2b 

for a job step 42-43 
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READ INTO option 234 
READ statement 

in BISAM 120,117 

causing errors 189-191 

in QISAM 117-120 
READY TRACE verb 72,187 
RECEIVE statement 234 
RECFM subparameter 

in compilation 415-416 

in DISPLAY statement 6 9-70 
record 

addressing 74,73 

blocked 69 

capacity 83 

dummy 83 

duplicate 423 

fields 305 

formats 74 

fixed-length 14 4 
spanned 148-154 
unspecified 145 
variable-length 145-148,151-152 

segments 149-150 

size, logical 

for SYSIN 415-416 
for SYSLIB 415-416 
for SYSPRINT 415-416 
for SYSPUNCH 415-416 

size restriction, physical 53-54 
RECORD CONTAINS clause 222 
RECORD KEY clause 

in BISAM 119-120 

in QISAM 119 
REDEFINES clause 222-223 
REF parameter 4 8 
REF subparameter 51,57 
referencing tables 241-246 
REGION parameter 

in EXEC statement 44-45 

in JOB statement 28-29 

main storage 28-29 

for MVT 28-29,44-45,380 

used in compilation 380 

used in execution 380 
relative file 

accessing 102 

allocating space for 102 

COBOL clauses for 108 

creating 101-102 

error processing 137 

Job Control Language for 109 

NOMINAL KEY, use of 100 

sample program 104-107 
releasing a job (RELEASE) 29 
relocation list dictionary 179,180,423 
removable volumes 55, 56 
Report Group descriptions 236-237 
Report Writer 

CODE clause 239 

floating first detail 240-241 

output floatings 240-241 

output line overlay 238-239 

size considerations 240-241,420 

SUM 237-238 
requesting a message class 28 
requesting a unit 51 
RERUN clause 327-330,25,42-43 
RERUN subroutine 399 



RES option 42, 41 
RESERVE clause 74 
reserved volumes 55-56 
RESET TRACt 187 
RESIDENT 267 

example 267 

linkage 267 

specifying 2b7 
Restart 

(see also Checkpoint/Restart* 

automatic 330 

for cataloged procedure 42,41 

checkpoint 331 

(see also Checkpoint) 

deferred 330-331 

initiating 327,329 

in a job 26-27 

in a job step 42-43 

RD parameter 329-330 

system routine 32 9 
RESTART parameter tsee RD parameter) 
RETAIN subparameter 56 
RETPD subparameter 58 
retrieving data sets 

cataloged 128 

example of 131 

noncataloged 129 

passed 129 

through an input stream 129-130 

with additional output 129 
return code 32-33,178 
return register 258 
REWRITE statement 

in BISAM 120 

in QISAM 118 
RLD (see relocation list dictionary) 
RLSE subparameter 53 
ROLL parameter 

in EXEC statement 4 5-46 

in JOB statement 4 5-46 

for MVT 29, 45-46 
ROUND subparameter 53 
run unit 258 



sample program output 383-394 
save area layout 265 
schedulers 

job 19 

master 19 

priority 19 

sequential 19 
SEARCH statement 244-245 
'searching a table 244-245 

binary method 24 4-245 

serially 245 
secondary quantity subparameter 

for SPACE 52 

for SPLIT 54 
segment work area 149, 154, 216 
segmentation feature 309,310,311 
SELECT sentence 

relationship to DD statement 134,72 

with user files 72 
SEND statement 2 34 
SEP parameter 51,47 
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SEQ option 36, 41 
sequential data sets 

DUMMY parameter 4 9 

on mass storage devices 123-124 
sequential schedulers 19 
SEPARATE CHARACTERS option 224-225 
serial search of a table 244-245 
SER subpararneter 57,4 8 
SET statement 242-243 
setting time limits 

on a job 27 

on a job step 42-43 
severity levels 178, 32-33 
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SHR subpararneter 58 
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SIGN clause 224-225 

single checkpoint 327 

single-segment message 23 4 

SIZE ERROR option 191 

SIZE option 

for compiler 36,41 

for loader 41, 42 
SL subpararneter 74-75 
Sort feature 

for ASCII files 307-308 

cataloging 304 

with Checkpoint/Restart 307-308 

considerations 382 

data sets 28 4 

DD statements 302-304 
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sort library 303 
SORT/MERGE 305-30 6 
sort subroutine 282 
S0RTLI3 DD statement 303, 304 
SORT WORK nn 302 

SORTWORKnn DD statement 302-304 
source module 15, 175 
SOURCE, option 36,41 
source program library 28 3 

(see also COBOL copy library) 
SOURCE-SUM correlation 236-237 
SPACE parameter 

in BSAM 78-79 

in creating data sets 122-127, 114 

in MVT 380-381,186 

in QISAM 114 

in Sort feature 303 

SPACEn option 37, 41 

subparameters 52-53 
SPACEn option 37, 41 
spacing 220-221 
spanned records 

blocked 149 

description 148-154 

direct processing 152-154 

formatting 149 



locating in dumps 215-216 
logical record area 152, 153 216 
segment work area 149,154,216 
sequential processing 150-152 
with Sort 302 

special characters in job control 
language 34,35 

specifying data set status and 
disposition 58-59 

specifying loader input 68, 280 

SPLIT parameter 

in creating data sets 122, 123, 124 
description 47,53-54 
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STACK subpararneter 77 
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standard labels 138-140 

standard sequential file 

accessing 74-79 

error processing 135 
standard user labels 139-140 
START statement 234-235 
STATE option 157 
STATE statement 202 
statistics 177 
step restart 

in a job 26-27 

in a job step 42-43 
STEPLIB DD statement 60 
stepname 32, 53-54 

STOP RUN statement, under MVT 381 
storage~~aiTccation~ ~ " " " ~ 
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considerations > 

for compilation 64,379,420,421 

for execution, joo step 44-45,380 

for linkage editing 421-422 

for overlay processing 273-279 

for Sort feature 302 306 307-308 382 

for source program 421-422 
storage considerations 421 

(see also main storage and storage 
allocation) 
storage map, for loader 183-184 
storage, mass (see mass storage) 
storage volume 55-56 
STRING statement 235 
SUBALLOC parameter 53-54 
SUBALLOC subpararneter 

in creating data sets 122. 124 

description 47,54 
subparameters 21 
subprogram 

and CANCEL statement 267 

and dynamic CALL 253, 254 

and static CALL 254 
subroutine library (see Horary) 
subroutines 

(see also library 

arithmetic 395,396 

conversion 395, 39b-397 

input/output 3 95 
SUL subpararneter 58 
SUM statement 237-238 
SUPMAP option 37,41,177,179,415-416 
SXREF option 38, 41 
SYMBOLIC QUEUE field 
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accessing queue structures 248, 249 

Queue Analyzer routine 248,249 
SYMBOLIC SUB-QUEUE name 248,249 
symbolic debugging 15 8-17 2 
SYMDMP option 

abnormal termination dump 158 

abnormal termination message 158 

Data Division dump 158 

and data-names 158 

general considerations 160 

operation of 160 

sample program 162-172 

specifying through PARM parameter 158 
SYNCHRONIZED clause 228 
synonym overflow 91, 95 
syntax-checking compilation 187 
SYSABEND DD statement 60,70,190 
SYSCHK DD statement 331 
SYSCP 18 

SYSDA 17,52,67,292 
SYSDBOUT DD card 202 
SYSIN DD statement 

in cataloged procedures 292-293,295,298 

for compilation 64-65, 66 

concatenating with SYSLIN 301 

logical record size for 415-416 

relationship to ACCEPT statement 70 

under MVT 380 
SYSIN-SYSOUT 38 
SYSLIB DD statement 

in cataloged procedures 299 

for compilation 65 

for linkage editing 68,67 

for loading 68 

logical record size for 415-416 
SYSLIN DD statement 

for compilation 65 

concatenating with SYSIN 301 

for linkage editing 66-67 

for loading 68,28 

logical record size for 415 
SYSLMOD DD statement 

with job library 286 

for linkage editing 67-68 
SYSLOUT DD statement 

for loading 68-69 
SYSOUT parameter 

relationship to DISPLAY statement 69-70 

in Sort feature 303-304 

subparameters 59-60 

under MVT 380 

use of 58-60,48,65,67,124 
SYSPRINT DD statement 

for compiler 64-65,66,173 

for linkage editor 67 

for loading 69,183-184 

logical record size for 415-416 
SYSPUNCH DD statement 

for compiler 64-65,66 

logical record size for 415-416 

relationship to DISPLAY statement 69-70 

S¥SSQ 18,52,67 
system catalog, creating 15 
system diagnostic messages 186 
system error recovery 134 
system-name 79,80 
system output messages 18 6 
system restart routine 329-330 



SYSTERM DD statement 64 

SYSUDUMP 60,70,190 

SYSUT1 

for compilation 79-80,379 
for linkage editing 68, 67 

SYSUT2 (see SYSUT1) 

SYSUT3 (see SYSUT1) 

SYSUT4 (see SYSUT1) 

SYS1.COBLIB 282,395-396 

SYS1.LINKLIB 67,282 

SYS1. PROCLIB 

adding procedures to 290 
description 2 89,282 

SYS1.SORTLIB 

description 282 

storage allocation for 382 



table elements 241-246 
tables 

building 2 46 

handling considerations 241-24b 

storage limitations 420-421 

subscripts 241 
tape (see magnetic tape) 
tape volume state 56-57 
task global table 176 
TCAM (telecommunications access 
method) 334 

data areas 216-218 
locating 216-218 
queue blocks 216,217 
SEND statement 216, 217 

service facilities 376-378 
operator control 376 
specifying operator commands 377 

writing compatible programs 367 
teleprocessing 

and CD entries 222 

and Communications Section 222 

environment 334 

and MCP 222 
temporary data set 

creating 125 

description 54 
temporary library 3 
temporary names 50 

temporary partitioned data sets 30 
terminal error messages 32-33 
termination of job 25 
TESTRUN sample program 162-172 
TGT (see task global table) 
TIME parameter 

for a job 27 

for a job step 43-44 
totaling, user label 140 
TRACE statement 

description 187-188 

relationship to SYSOUT DD statement 7 
TRACE subroutine 3 96-397 
track 

addressing 73,81-82 

capacity 90,92,93 

identifier 81-82 

index 110 

space for 84,85,86,88,114,116 
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TRACK- AREA clause 

in BSAM 121 
TRACK-LIMIT clause 84,85,88,87 
trailer labels 137-138 
TRANSFORM statement 235 
TRANSFORM subroutine 397-398 
TRK subparameter 52 
TRTCH subparameter 77 
TRUNC option 37,41 
two-part region 29 
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fixed-length 144 

permissible file techniques 74 

spanned 149 

variable- length 145,147 
UNCATLG subparameter 59 
undefined length records 

(see unspecified length records) 
unequal fields 224 
UNIT parameter 

creating data sets with 121-127 

description 51, 47 

multi volume data sets using 8 8-89 

retrieving data sets with 129 

sort programs using 303,304 

subparameter s 51, 52 
unit record data set 122 

unit record device, DD statement for 132 
unit, requesting 51 
unspecified length- records- 145 
UNSTRING 

definition 235 

example 236 
USAGE clause 

causing errors 192 

efficient use of 221, 224-225 

example 176 
USE AFTER ERROR Option 

description 135 

in file processing techniques 410-414 
USE BEFORE LABEL option 132-133 
user-defined files 72-73 
user file processing 

error processing 135-136 

file processing techniques 73 

labels 138-140 

user-defined files 72-73 
user lable 

procedure 141 

totaling 140 
user labels 138-141 
user libraries 282-283, 60 
user-specified data sets 68 
USING option 302 
utility data sets 

for compilation 64 

for linkage editing 66 
utility programs 

IEBUPDTE 190,283,286 

IEHLIST 218-219 

IEHMOVE 281 

IEHPROGM 218-219 

ILBDSRT0 304 



variable elngth 

records 145-148,150-152,307-308 
verbs 232-237 
volume 

definition 15 
labels 

nonstandard 138 
standard 138-139 
magnetic tape 56 
mass storage 55, 5b 
nonspecific 55 

parameter (see VOLUME parameter) 
permanently resident 55-56 
private 55 
public 55 
reference 

nonspecific 55 
specific 55 
removable 56 
reserved 56 
specific 55 
state 

allocation 55-56 
magnetic tape 56 
mass storage 55, 5b 
mount 56 
storage 53-56 
volume 

switching 88, 87 
volume-count subparameter 57 
VOLUME parameter 

creating data sets with 122-124 

description 53-55 

retrieving data sets with 129 
subparameters 56-57 
with UNIT parameter 51 
volume-sequence number subparameter 
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222-223 
234 
222 

234 



W (warning severity level) 178, 32-33 
warning, used as a severity level 

(W) 178,32-33 
word, beginning address of 53 
Working Storage 

locating in dumps 

READ INTO Option 

separate modules 

WRITE FROM option 
WRITE AFTER ADVANCING option 

restriction with PRTSP parameter 77 

use of 75 
WRITE AFTER POSITIONING option 

restriction with PRTSP parameter 77 

use of 7 5 
WRITE FROM option 234 
WRITE statement, causing errors with 19 3 



XREF option 

for compilation 38,41 

for linkage editing 40,41,182 
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